Run Circles Around GeoJSON, Beginner to Advanced with HERE XYZ

By Jayson DeLancey | 12 October 2018

Are you just getting started with GeoJSON? If you are not already familiar with the format but want to make a map with HERE XYZ (public beta) you may be trying to come up to speed quickly to take advantage of the geospatial data storage in HERE XYZ Hub or rendering capabilities for customization in HERE XYZ Studio. You can read the documentation for GeoJSON Basics but let's start with a quick primer that will have you drawing circles in no time.

GeoJSON Primer 

What is it?

If you are familiar with JavaScript and Web Services you already know about JavaScript Object Notation (JSON) as a way to syntactically represent the values of variables, arrays, and dictionaries in a text file. GeoJSON, is a standardized specification for how to represent those geospatial objects so that anybody can understand what they mean and semantically process it with software.

A few months ago we celebrated 10 years since the original GeoJSON spec was proposed. The IETF would go on to formalize it as RFC 7946. As much fun as reading a technical spec is, here’s what you need to know.

COORDINATES

We're just talking about latitude and longitude here but the order matters and in the case of GeoJSON X comes before Y which means longitude first in the order [longitude, latitude, elevation].

"coordinates": [-120.010789634, 39.094537102]

TYPE

If you've worked with other Geospatial data formats, you will quickly recognize some similarities. With coordinates representing a location on the globe, we can add a type that defines the shape of basic geometry. The Point, LineString, and Polygon represent the three primary types.

Screen Shot 2018-10-10 at 6.27.22 PM

POINT

The Point is rendered as a dot.

{

  "type": "Point",

  "coordinates": [-120.01078, 39.09453]

}

LINESTRING

The LineString is rendered as a series of points connected with a line.

{

  "type": "LineString",

  "coordinates": [

    [-117.49389, 40.73069],

    [-115.98877, 37.95294]

  ] 

}

POLYGON

The Polygon is a chain of line segments in a loop for the purpose of rendering a filled shape. The first and last coordinates are identical to make sure the linear ring is closed.

{

  "type": "Polygon",

  "coordinates": [

    [-113.65967, 40.12857],

    [-113.62671, 38.85690],

    [-111.05591, 39.34287],

    [-111.25366, 40.22930],

    [-111.36352, 40.12910],

    [-113.65967, 40.12857]

  ]

}

MULTI

In addition to the basic geometry types there are MultiPoint, MultiLineString, and MultiPolygon. It may not be a surprise to know that these are just simply extensions of the basic types to represent the coordinates as an array of arrays. It is not necessary to use these types but it becomes helpful for the compactness and parsing of the resulting GeoJSON file. 

{

  "type": "MultiPoint",

  "coordinates": [

    [-117.49389, 40.73069],

    [-115.98877, 37.95294]

  ]

}

FEATURE

To add context to your geometry there is a Feature type. By enclosing both geometry and properties together you can add real world metadata or attributes to the shapes defined in the geometry being rendered.

{

  "type": "Feature",

  "properties": {

     “label”: “Favorite Place”

    },

  "geometry": [{

    "type": "LineString",

         "coordinates": [

          -120.010789634,

          39.094537102,

          0

         ]

    }]

}

You can also define a FeatureCollection that like the Multi types is a list of lists for defining many features at once.

Drawing with HERE XYZ Studio

Knowing GeoJSON is one thing, creating it is something else. So, how do you get GeoJSON in the first place? A few options:

  1. There are many public / open data sources that provide GeoJSON data for download.
  2. You can fire up a text editor and start typing.
  3. You can use HERE XYZ Studio and GeoJSON Tool.

As you may have seen in the XYZ Studio Quick Tour, Studio has a mode where you can create or edit content

XYZ-Editing-Clip

If you want to export or download this layer, you can use the HERE CLI from a bash shell to export the space:

here xyz show {SPACE_ID} -r > output.geojson

The -r dumps out the raw GeoJSON content which you can pipe into a file. You'll notice that Studio stores the geometry in a FeatureCollection along with some metadata properties.

GeoJSON Tool

Alternatively, you can also use GeoJSON Tool which has a built-in text editor and viewer for writing GeoJSON and viewing the results. It has an easy to remember URL as well -- http://geojson.tools.

Screen Shot 2018-10-09 at 2.14.17 PM

Circles

Drawing circles could be handy if trying to represent radius around an area such as the no-fly zones for drones around an airport or the flight radius of a nesting European Swallow.

Using XYZ Studio you can customize your map to change the look and feel which means you can bump up the size and color of a Point to look like a circle.

Screen Shot 2018-10-09 at 10.03.15 AM

You may be tempted to draw a circle in GeoJSON, but first think about what you’re trying to display.  Scaling the size of Points is best if you wanted to show the magnitude of an earthquake or to scale a Point based on a property like we did in the Madrid Air Quality Tutorial.

If you wanted to show a circle with a specific radius (for swallows), remember that GeoJSON doesn't natively have a Circle type. This was intentional as drawing circles on a flat surface which is really a spheroid gets tricky.

You can use your favorite programming language or tools to make a Polygon with a large number of sides to approximate a circle. Depending on the radius and zoom level you may want to experiment a bit.

Here's a simple example with Python:

You’ll need to setup a Python environment and pip install shapely geojson for this to work properly. 

(You can also draw a circle with a specific radius in miles or kilometers -- turf.js is a handy tool for that. But keep in mind you’ll be dealing with projections! This means a 5km radius circle will look like an oval once you leave the equator and will change shape at different latitudes.)

Copying and pasting the output from running that Python code into geojson.tools renders a nice circle in the Gulf of Guinea.

Screen Shot 2018-10-10 at 7.08.25 AM

Next Steps

This was not an exhaustive study of everything you can do with GeoJSON but aimed to get you started.  From here you should check out the GeoJSON Basics documentation for more detailed examples. From there you can start using the GeoJSON Tool or HERE XYZ Studio as interactive editors to experiment with GeoJSON for yourself.