Learn about this format for encoding geographic data structures for use in maps.
The GeoJSON Format is a widely used standard for encoding geographic data in a lightweight and easy-to-read way. It uses JSON (JavaScript Object Notation) to describe geographic shapes such as points, lines, and polygons, along with metadata about those shapes.
GeoJSON is ideal for data visualization because it provides a precise yet simple way to define geographic features. For example, a GeoJSON file might represent country borders, city locations, or river paths. GeoJSON's compatibility with modern mapping tools makes it a common choice for projects that involve geographic data. In Mappica, the basemap layer in Map elements is stored as a GeoJSON file.
If you are not familiar with JavaScript arrays and objects, learning the basics of these data structures can be a helpful first step before creating or editing GeoJSON files.
The GeoJSON format organizes geographic data into a structured hierarchy that makes it easy to work with multiple geographic features. A feature represents a single unit of geographic data, such as a point, line, or polygon, and includes associated properties (e.g., name, population, category). Features can represent a wide range of real-world entities like cities, roads, lakes, or state boundaries.
At the top level, GeoJSON files containing multiple features use a FeatureCollection, which serves as a container for an array of features. Each feature is stored as an individual entry within the collection, with its own geometry and properties.
For example, a GeoJSON file containing the boundaries of two U.S. states would have this overarching structure:
{
"type": "FeatureCollection",
"features": [
// Individual state features would go here
]
}
Each feature is assigned certain attributes:
The code below shows the structure with placeholders for the coordinate data:
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"geometry": {
"type": "Polygon",
"coordinates": []
},
"properties": { "name": "Colorado" },
"id": "08"
},
{
"type": "Feature",
"geometry": {
"type": "Polygon",
"coordinates": []
},
"properties": { "name": "Wyoming" },
"id": "56"
}
]
}
For a given feature, the coordinates attribute should be structured based on the accompanying geometry type. Each geometry type has specific requirements for how coordinates should be organized:
Point Coordinates
Point geometries represent a single location and use a simple array with longitude and latitude values.
Structure: [longitude, latitude]
{
"type": "Point",
"coordinates": [-105.0, 39.7]
}
The example above shows Denver, Colorado.
MultiPoint Coordinates
MultiPoint geometries represent multiple separate locations and use an array of coordinate pairs.
Structure: [[lon1, lat1], [lon2, lat2], ...]
{
"type": "MultiPoint",
"coordinates": [
[-105.0, 39.7],
[-105.1, 40.6]
]
}
The example above combines Denver and Fort Collins, Colorado.
LineString Coordinates
LineString geometries represent connected line segments and use an array of coordinate pairs that form a path.
Structure: [[lon1, lat1], [lon2, lat2], [lon3, lat3], ...]
{
"type": "LineString",
"coordinates": [
[-105.0, 39.7],
[-105.1, 40.6],
[-106.8, 39.6]
]
}
The example above shows a path through Colorado.
MultiLineString Coordinates
MultiLineString geometries represent multiple separate line paths and use an array of LineString coordinate arrays.
Structure: [[[lon1, lat1], [lon2, lat2]], [[lon3, lat3], [lon4, lat4]]]
{
"type": "MultiLineString",
"coordinates": [
[
[-105.0, 39.7],
[-105.1, 40.6]
],
[
[-106.8, 39.6],
[-107.6, 39.55]
]
]
}
The example above combines two separate paths in Colorado.
Polygon Coordinates
Polygon geometries represent closed areas and use an array of coordinate arrays. The first array defines the outer boundary, and additional arrays define holes within the polygon.
Structure: [[[lon1, lat1], [lon2, lat2], [lon3, lat3], [lon1, lat1]]]
{
"type": "Polygon",
"coordinates": [
[
[-109, 37],
[-102, 37],
[-102, 41],
[-109, 41],
[-109, 37]
]
]
}
The example above shows a rectangular outline. Note that polygons are closed, so their first and final coordinate pairs must match.
Note that when building choropleth maps in Mappica, each feature represents a selectable item that can be assigned a color. Thus, when MultiPoint, MultiLineString, or MultiPolygon is used to join together points inside a feature, clicking on any of these points, lines, or polygons selects all of them. If you want individual points, lines, and polygons to each be selectable or assigned colors independently, you should represent them as separate features within a FeatureCollection.
An additional geometry type not listed earlier is the GeometryCollection. This allows you to group multiple geometry types—such as Point, LineString, Polygon, or others—into a single feature. In a GeometryCollection, instead of specifying coordinates as in other geometry types, the geometry object includes a geometries property. This is an array of individual geometry objects, each with its own type and coordinates.
An example of a GeoJSON file using this structure is displayed below:
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"geometry": {
"type": "GeometryCollection",
"geometries": [
{
"type": "Point",
"coordinates": [-104.9903, 39.7392]
},
{
"type": "LineString",
"coordinates": [
[-104.9903, 39.7392],
[-105.0844, 40.5853]
]
},
{
"type": "Polygon",
"coordinates": [
[
[-109.05, 37],
[-102.05, 37],
[-102.05, 41],
[-109.05, 41],
[-109.05, 37]
]
]
}
]
},
"properties": {
"name": "Colorado Geometries"
}
}
]
}
To ensure your GeoJSON file works seamlessly in your visualization, follow these steps to prepare and validate it:
Coordinates: First, ensure that your file uses the WGS 84 coordinate system (EPSG:4326), which is the global standard for representing geographic locations using latitude and longitude. In WGS 84, coordinates are expressed in decimal degrees, with longitude ranging from -180 to 180 and latitude ranging from -90 to 90. If your data uses a different system—such as coordinates measured in meters or feet, or a non-standard projection—convert it to WGS 84 before uploading it to Mappica.
File Size: Simplify overly detailed shapes in your GeoJSON. Complex polygons or lines with excessive detail can result in large files that are slow to render. Use in-built simplification functionality in Mappica's basemap editor to retain the essential geometry needed for your visualization.
Format: If your data is in a format like shapefiles, Mapshaper can also convert it to GeoJSON. During conversion, take the opportunity to clean up any unnecessary fields or features.
Validate: Once prepared, validate your GeoJSON file using a tool such as GeoJSONLint. This tool checks for errors in your file's structure, such as missing brackets, improperly closed polygons, or incorrect data types.
Once the GeoJSON file has been uploaded to Mappica, confirm that all geographic features and metadata display as expected. Verify that the properties you've included—such as id or name—align with the data you plan to visualize. Change the Projection and Rotation of the basemap as needed.
By following these steps, you can ensure your GeoJSON file is properly prepared and ready to support your data visualization project.