GeoJSON

GeoJSON is a text-based format written in JavaScript Object Notation (JSON) that is sometimes used for interchange of vector data, drawings.   Manifold can import and link GeoJSON files.  Manifold can also export drawings to GeoJSON files.

 

Current Manifold builds have a limit of 2 GB per JSON or GeoJSON file.  This limitation will be removed in upcoming builds, allowing use of JSON and GeoJSON files that exceed 2 GB.

 

Manifold provides four different dataports for importing or linking text files containing data in JSON:

 

 

The GeoJSON and JSON dataports are different, since GeoJSON is a well-specified standard, while a generic JSON file need not follow any standard for data organization.  As a practical matter, JSON files are thus useful for interchanging tables in relatively calm use of JSON, such as arrays.

 

Manifold's GeoJSON dataport automatically recognizes GeoJSON content in files that end with a .geojson extension.   When files containing GeoJSON data end in a .json extension, we can still import them as GeoJSON files, but we must tell Manifold to use the GeoJSON dataport and not the JSON dataport.  

 

To import a GeoJSON format file:

 

  1. Choose File - Import from the main menu.

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

  3. Click the file to load the file name into the import File name box.

  4. If the file uses a .json extension, choose GEOJSON Files (*.geojson) in the type box.

  5. Press the Import button.

  6. 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 folder containing desired .geojson or .json files.

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

  4. If the files use a .json extension, choose GEOJSON Files (*.geojson) in the type box.

  5. Press the Import button.

  6. 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 GeoJSON 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 GeoJSON file into the project, leaving the data resident in the GeoJSON 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.

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.

 

 

Choose File - Import.  

 

 

Navigate to the desired .json or .geojson file and click it.   In this case, Microsoft publishes GeoJSON data using a file extension of .json, so we will first choose the file and then in the next step specify the GeoJSON dataport should be used.

 

 

Next, in the file type box we choose GEOJSON Files (*.geojson).   The dialog display clears, since there are no files with a .geojson extension in the folder, but the name of the file we want remains in the File name box.   

 

Press Import.

 

 

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

 

 

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

 

 

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.  

 

 Manifold Viewer is read-only software: exporting to a project or to a different format requires Release 9.

 

 

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

 

 

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.

 

 

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.

 

 

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.

Example: Accidentally Importing a GeoJSON File as a JSON File

Given the habit of some authors to publish GeoJSON files using a  .json file extension instead of a .geojson file extension, it is probably only a matter of time before we double-click on a .json file, which automatically imports it as a JSON file, when instead it is a GeoJSON file.    It is easy to tell when that happens, and easy to fix.

 

Suppose we take the DistrictofColumbia.json file used above in this topic, and instead of importing it as a GeoJSON file we just double-click it in the Import dialog to import it as a JSON file.

 

 

Instead of getting a drawing, we will get a table, usually called features, that when opened will be seen to contain for each record a geometry field full of JSON text that gives the coordinates for point, line or area objects.    That is our immediate tip-off that we imported a GeoTIFF file as a JSON file.   We can fix that by re-importing the file using the procedure given in this topic, choosing GEOJSON Files (*.geojson) for the type of import.

 

Notes

GeoJSON 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 .geojson or .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 Servers

 

JSON

 

JSON Servers

 

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