GeoJSON / JSON

GeoJSON is an text-based format written in JavaScript Object Notation (JSON) that is sometimes used for interchange of vector data.   It is often is found in files with a file name extension of .geojson or, more recently, a file name extension of .json.   Microsoft's publication of a massive, 125 million building data set for free and open use in GeoJSON format using files with an extension of .json has effectively tipped the scales toward using .json as a standard file name extension for files that contain geographic data in GeoJSON format.  

 

Manifold's GeoJSON dataport automatically recognizes GeoJSON content in files that end with either a .geojson or .json file extension.  Manifold automatically reads TopoJSON when a GeoJSON file contains TopoJSON.  Geometry collections are expanded automatically.  

 

To import a GeoJSON format file:

 

  1. Choose File - Import from the main menu.

  2. Navigate to the desired .json or .geojson file.

  3. Double-click the file to import it.

  4. A new drawing and table will appear in the Project pane.

 

 

To import multiple GeoJSON format files:

 

  1. Choose File - Import from the main menu.

  2. Navigate to the desired .json or .geojson files.

  3. Ctrl-click each desired file to highlight it.

  4. Press the Import button.

  5. A new drawing and table will appear in the Project pane for each imported file.

 

New Data Source Dialog / File - Link

The most efficient way to import a .json file into a project is to use File - Import.   If we like, we could use either File - Link or File - Create - New Data Source, to link the .json file into the project, leaving the data resident in the .json file.   That is not recommended since GeoJSON is a text format that is much slower than fast binary formats, and  far slower than native Manifold project storage. tech_angus_sm.png

 

Important: The GeoJSON dataport's limitation to 2 GB of text currently disallows use of Microsoft's Texas and California files, both of which are larger than 2 GB as GeoJSON text.  This limitation will be removed in upcoming builds, allowing use of these and other GeoJSON files that exceed 2 GB.

 

Example

We will import a .json file that provides vector footprints of buildings in the District of Columbia.  This is part of the collection of all US building footprints recently published as open data by Microsoft.

 

eg_import_geojson01_01.png

 

Choose File - Import.  

 

eg_import_geojson01_02.png

 

Navigate to the desired .json or .geojson file and double-click it.

 

eg_import_geojson01_03.png

 

The file imports as a drawing and the drawing's table.   Double-click the drawing to open it.  

 

eg_import_geojson01_04.png

 

The Component pane shows the drawing has been correctly imported with the specified Latitude / Longitude coordinate system correctly assigned.   We can see from the Status Bar's Scale and Position readouts the drawing is correctly positioned and scaled.

 

eg_import_geojson01_05.png

 

Back in the Project pane we can double-click open the drawing's table. We can see that this particular data set from Microsoft has only one field, the geometric shape for each vector object, all of which are areas.

Comparative File Sizes

To get a feel for the relative storage efficiency of GeoJSON, we can export the data to different formats.  Note that Manifold Viewer is read-only software: exporting to a project or to a different format requires Release 9.

 

eg_import_geojson01_06.png

 

To export the entire project, we can choose File - Export Project.   

 

eg_import_geojson01_07.png

 

We choose to export the project to Manifold's archival project format, .mxb.  MXB is a compressed, archival format that is not "instant open" like Manifold's ultra-fast .map project format, but it is compact and very efficient for storage.

 

eg_import_geojson01_08.png

 

After exporting the project, we can compare file sizes as shown by Windows File Explorer.    The .mxb is slightly smaller than a zipped archive of the .json file, and much smaller than the .json file.  The difference would be greater for larger files as the overhead involved in the .mxb becomes a smaller percentage of the overall storage size.

 

eg_import_geojson01_09.png

 

We could also use File - Export to export the drawing to a shapefile.   The shapefile ensemble, as seen above, ends up being significantly larger, over 9 MB in size for the .shp and .shx files.

Multi-type Geometry

GeoJSON, like GML, KML, and similar formats, can include geometry data for each object that mixes one or more geometry types.  Geometry values declared as multi-type but with all parts having the same underlying type, such as all areas, all lines, or all points, will preserve that underlying type. Geometry values declared as multi-type that mix different types are converted as follows:

 

 

See the discussion and example in the KML, KMZ Google topic.

Notes

JSON Files can be Larger than Expected - The larger size of GeoJSON format files for relatively small data may come as a surprise.  That happens because storing floating point numbers as text requires more space than storing numbers as binary data.   

 

GeoJSON is a "geographic" format for interchange of vector data using text written in JavaScript Object Notation (JSON).  In terms of the amount of file space consumed to convey information, it takes more space than binary formats, routinely requiring file sizes that are five, ten or even twenty times larger than a more compact binary format. 

 

For example, the first polygon in Microsoft's data set for the District of Columbia in GeoJSON is written in plain text within the DistrictofColumbia.json file as:

 

{"type":"Feature","geometry":{"type":"Polygon","coordinates":[[[-77.016383707523346,38.961773895075027],[-77.016383707523346,38.961859404361192],[-77.0165553689003,38.961859404361192],[-77.0165553689003,38.961773895075027],[-77.016383707523346,38.961773895075027]]]}}

 

The above polygon contains only five vertices, yet in the GeoJSON text format it requires 267 bytes in ASCII or 534 bytes for Unicode in international settings.    The same polygon in a binary format could easily be encoded in 25 or fewer bytes:  five, four-byte floating point numbers plus an extra byte or so for encoding the object type.   The result is that .json files tend to be larger than binary formats.

 

JSON is a fine format for quick interchange of relatively small data, or to publish data which will then be saved in a faster working format.

 

Geometry collections - Reading geometry collection values automatically merges individual values of the same underlying type used in Manifold geometry, such as area, line or point, with differences between subtypes such as line and multiline being ignored.   The result of the merge is returned.   This applies to all data which support geometry collection values, including WKB, GeoJSON, JSON, native geometry in database-specific formats, and so on.

 

Reading geometry collection values with individual values of mixed underlying types automatically converts areas to lines and lines to points in order to return all coordinates. Example: reading a geometry collection with an area and several points will return a multipoint containing all coordinates of all individual values.

 

3D conversions - Geometry values with mixed 2Dand 3Dcoordinates in GML, GeoJSON, and TopoJSON are automatically converted to 3D with 2D coordinates padded with zeros.

 

Download Microsoft's Data - We can download Microsoft's data from their US Building Footprints page on Github.   Thank you, Microsoft!

 

See Also

Drawings

 

Tables

 

Style

 

Web Servers

 

File - Import

 

File - Create - New Data Source

 

GeoJSON / JSON

 

Example: Import GeoJSON / JSON File - Import vector footprints for all buildings in the District of Columbia, using a GeoJSON file published as open data by Microsoft.