Package gov.usgs.earthquake.nshmp.geo.json

Class GeoJson

  • public abstract class GeoJson
extends Object
    Entry point for creating and parsing GeoJSON features and feature collections.

    To create a GeoJSON feature collection string, use a builder and add features per the example below: 

     String geojson = GeoJson.builder()
     .add(Feature.point(Location.create(34, -117))
         .id("featureId")
         .properties(Map.of(
             "title", "Feature Title",
             "color", "#ff0080"))
         .build())
     .add(Feature.polygon(
         LocationList.create(
             Location.create(34, -117),
             Location.create(35, -118),
             Location.create(37, -116),
             Location.create(38, -117)))
         .id(3)
         .build())
     .build()
     .toJson();

    Where the GeoJSON string created is: 

     {
   "type": "FeatureCollection",
   "features": [
     {
       "type": "Feature",
       "id": "featureId",
       "geometry": {
         "type": "Point",
         "coordinates": [-117.0, 34.0]
       },
       "properties": {
         "title": "Feature Title",
         "color": "#ff0080"
       }
     },
     {
       "type": "Feature",
       "id": 3,
       "geometry": {
         "type": "Polygon",
         "coordinates": [
           [
             [-117.0, 34.0],
             [-118.0, 35.0],
             [-116.0, 37.0],
             [-117.0, 38.0]
           ]
         ]
       },
       "properties": {}
     }
   ]
 }

    Note in the example above that features have their own geometry-specific builders. Features supply Feature.toJson(), Feature.toJsonTree() and Feature.write(Path) methods to output single-feature GeoJSON directly.

    Parse GeoJSON to a feature or feature collection using static from* methods as follows: 

     Feature f = GeoJson.from(String | Path | Url).toFeature();
 FeatureCollection fc = GeoJson.from(String | Path | Url).toFeatureCollection();

    Once parsed, the feature geometry may be accessed as objects in the geo package (e.g. Location, LocationList, etc...). This requires some prior knowledge of the contents of the parsed GeoJSON.

    This class does not allow the creation of empty feature collections or features with null geometry.

    Author:
    U.S. Geological Survey

    • Method Detail

      • from

        public static GeoJson from​(String json)
        Create a GeoJSON from a string.
        Parameters:
        json - string to read

      • from

        public static GeoJson from​(Path json)
        Create a GeoJSON from a file path.
        Parameters:
        json - file path to read

      • from

        public static GeoJson from​(URL json)
        Create a GeoJSON from a URL. Use this method when reading resources from a JAR.
        Parameters:
        json - URL to read

      • validateBoundingBox

        public static LocationList validateBoundingBox​(LocationList locations)
        Checks that bounding box location list contains 5 coordinates defining a mercator lat/lon rectangle.
        Parameters:
        locations - to check
        Returns:
        the supplied locaiton list

      • expandRectangularArea

        public static LocationList expandRectangularArea​(LocationList locations)
        Checks that the supplied location list defines a rectangular lat/lon area and returns a slightly expanded version that will enclose points on the borders of the area. Points coincident with east and north edges of polygons are considered inside as a result.

      • builder

        public static GeoJson.Builder builder()
        A reusable GeoJSON builder.