Overview
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.
Features
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 the U.S. states of Colorado and Wyoming would have this overarching structure:
{
"type": "FeatureCollection",
"features": [Colorado_Feature, Wyoming_Feature]
}
Type, Geometry, and Properties
Each feature is assigned certain attributes:
- Type: Always set to "Feature" to identify the object as a GeoJSON feature.
- Geometry: Defines the shape of the feature. The geometry is assigned a type, which could be "Point" (a specific location), "MultiPoint" (multiple locations), "LineString" (a continuous path), "MultiLineString" (multiple paths), "Polygon" (a closed area), "MultiPolygon" (multiple closed areas), or "GeometryCollection" (a mix of geometries). The geometry is also assigned coordinates, which specify the location or shape of the feature using an array of
[longitude, latitude] pairs. The exact format of the coordinates depends on the geometry type, which is explained in more detail below. - Properties: A collection of metadata or descriptive attributes about the feature, such as { "name": "Utah" }.
- ID (optional): A unique identifier for the feature, such as "08" for Colorado.
The code below updates the earlier example to include the attributes listed above. For simplicity, we leave placeholders for the coordinates, which are discussed in the next section:
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"geometry": {
"type": "Polygon",
"coordinates": Colorado_Coordinates
},
"properties": { "name": "Colorado" },
"id": "08"
},
{
"type": "Feature",
"geometry": {
"type": "Polygon",
"coordinates": Wyoming_Coordinates
},
"properties": { "name": "Wyoming" },
"id": "56"
}
]
}
Coordinates
For a given feature, the coordinates attribute should be structured based on the accompanying geometry type:
"coordinates": [lon, lat]
"coordinates": [-105, 39.7]
The example shows Denver, Colorado.
"coordinates": [
[lon1, lat1],
[lon2, lat2]
]
"coordinates": [
[-105, 39.7], [-105.1, 40.6]
]
The example combines Denver and Fort Collins, Colorado.
"coordinates": [
[lon1, lat1],
[lon2, lat2]
]
"coordinates": [
[-105, 39.7],
[-105.1, 40.6],
[-106.8, 39.6]
]
The example shows a path through Colorado.
"coordinates": [
[
[lon1, lat1],
[lon2, lat2]
],
[
[lon3, lat3],
[lon4, lat4]
]
]
"coordinates": [
[
[-105, 39.7],
[-105.1, 40.6]
],
[
[-106.8, 39.6],
[-107.6,39.55]
]
]
The example combines two paths in Colorado.
"coordinates": [
[
[lon1, lat1],
[lon2, lat2],
[lon3, lat3],
[lon1, lat1]
]
]
"coordinates": [
[
[-109, 37],
[-102, 37],
[-102, 41],
[-109, 41],
[-109, 37]
]
]
The example shows an outline of Colorado. The polygon is closed, so its first and final value pair match.
"coordinates": [
[
[
[lon1, lat1],
[lon2, lat2],
[lon3, lat3],
[lon1, lat1]
]
],
[
[
[lon3, lat3],
[lon4, lat4],
[lon5, lat5],
[lon3, lat3]
]
]
]
"coordinates": [
[
[
[-109, 37], [-102, 37], [-102, 41], [-109, 41], [-109, 37]
]
],
[
[
[-111, 41], [-104, 41], [-104, 45], [-111, 45], [-111, 41]
]
]
]
The example shows combined outlines of Colorado and Wyoming. The polygons are closed, so their first and final value pairs match.
The code below completes the earlier example, incorporating coordinates for the two polygon features, Colorado and Wyoming:
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"geometry": {
"type": "Polygon",
"coordinates": [
[
[-104.053011, 41.003906],
[-109.04798, 40.998429],
[-109.042503, 37.000263],
[-102.042974, 36.994786],
[-102.053927, 41.003906],
[-104.053011, 41.003906]
]
]
},
"properties": { "name": "Colorado" },
"id": "08"
},
{
"type": "Feature",
"geometry": {
"type": "Polygon",
"coordinates": [
[
[-104.053011, 41.003906],
[-104.058488, 44.996596],
[-111.05254, 45.002073],
[-111.047063, 40.998429],
[-109.04798, 40.998429],
[-104.053011, 41.003906]
]
]
},
"properties": { "name": "Wyoming" },
"id": "56"
}
]
}
Combining Geometries
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 (e.g., Point, LineString) 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"
}
}, ...
]
}
Preparing GeoJSON Files
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 (e.g., [-74.006, 40.7128] for New York City). 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 the "Simplify" feature available at Mapshaper.org to reduce file size while retaining 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.
