GeoJSON 101: The Developer's Guide to Geographic Data on the Web

GeoJSON is the standard format for geographic data on the web. It's JSON with a specific structure for geometry and properties, parseable with native JSON.parse(), and supported by every major mapping library. If you're building web features with location data, GeoJSON is your format.

If you're building anything with maps on the web, you'll encounter GeoJSON constantly. It's become the de facto standard for exchanging geographic data between servers and browsers, supported by every major mapping library. Understanding GeoJSON isn't just useful, it's essential for modern web development involving location data.

What GeoJSON Is and Why It Matters

GeoJSON is a format for encoding geographic data structures using JavaScript Object Notation. It emerged in 2008 as a community-driven specification, later formalized as RFC 7946 in 2016. The format's success comes from its simplicity: it's just JSON with a specific structure for representing geometry and associated properties.

Before GeoJSON, developers often struggled with XML-based formats like KML and GML, which required specialized parsers and didn't integrate well with JavaScript applications. GeoJSON changed that by providing a format that JavaScript could parse natively with JSON.parse(). No special libraries needed, no XML namespaces to navigate, just clean data structures.

The Structure: Features and GeoJSON Geometry

GeoJSON organizes data into Features and FeatureCollections. A Feature represents a single geographic entity, combining geometry with arbitrary properties. A FeatureCollection groups multiple Features together, which is what you'll work with most often.

Here's the basic structure of a FeatureCollection containing a single point:

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [-73.9857, 40.7484]
      },
      "properties": {
        "name": "Empire State Building",
        "height": 443,
        "built": 1931
      }
    }
  ]
}

The geometry object describes the shape and location. GeoJSON supports seven geometry types: Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, and GeometryCollection. Points represent single locations, LineStrings represent paths or routes, and Polygons represent areas with boundaries.

The properties object is where you store all your attribute data. It can contain any valid JSON: strings, numbers, booleans, arrays, or nested objects. This flexibility means you can attach rich metadata to each feature without any schema constraints.

The Coordinate Order Gotcha

Here's where many developers stumble: GeoJSON uses longitude-latitude order, not latitude-longitude. Those coordinates above, [-73.9857, 40.7484], represent longitude first, then latitude. This is the opposite of how we typically speak about locations and how many APIs return coordinates.

The reasoning follows mathematical convention. Longitude corresponds to the x-axis (east-west position), and latitude corresponds to the y-axis (north-south position). In coordinate geometry, we write points as (x, y), so GeoJSON writes them as [longitude, latitude].

This catches developers constantly. If your points are appearing in the ocean or on the wrong continent, check your coordinate order first. It's almost always the culprit.

Using GeoJSON with Mapping Libraries

Every major web mapping library handles GeoJSON natively. With Leaflet, adding GeoJSON to a map takes just one line:

const geojsonData = await fetch('/api/map/abc123').then(r => r.json());
L.geoJSON(geojsonData).addTo(map);

Leaflet automatically creates appropriate layers for each geometry type. Points become markers, LineStrings become polylines, and Polygons become filled shapes. You can customize this behavior by passing options to L.geoJSON(), including functions that style features based on their properties or create custom popups.

Mapbox GL JS works similarly, though it treats GeoJSON as a data source that you then style with layers:

map.addSource('locations', { type: 'geojson', data: geojsonData });
map.addLayer({
  id: 'location-points',
  type: 'circle',
  source: 'locations',
  paint: { 'circle-radius': 8, 'circle-color': '#3b82f6' }
});

OpenLayers, Google Maps, and other libraries all provide similar GeoJSON support. The format's ubiquity means you can switch mapping libraries without changing your data format.

How Notion to Maps Exports GeoJSON

When you export a Notion database to GeoJSON, the output follows best practices for web consumption. Each row in your database becomes a Feature, with the Place property providing the geometry and all other properties included in the properties object.

The export preserves your Notion property names, so a database with "Name", "Category", and "Rating" columns produces features with those exact property keys. This makes it straightforward to style markers based on category or display ratings in popups.

The exported GeoJSON is valid according to RFC 7946, meaning it works with any compliant library or tool. You can validate it with online tools like geojsonlint.com, visualize it on geojson.io, or process it with command-line tools like ogr2ogr.

Beyond the Basics

GeoJSON's simplicity is its strength, but the specification includes a few advanced features worth knowing. The optional id field on Features provides a stable identifier for updating or referencing specific features. The bbox (bounding box) field on FeatureCollections helps clients quickly determine the geographic extent of the data without parsing every coordinate.

For very large datasets, consider GeoJSON's streaming-friendly cousin, newline-delimited GeoJSON (GeoJSONSeq), where each line is a complete Feature. This allows processing files larger than available memory.

Whether you're building a store locator, visualizing travel routes, or creating an interactive data dashboard, GeoJSON provides the foundation. Its combination of simplicity, flexibility, and universal support makes it the natural choice for geographic data on the web. Need other formats? Notion to Maps also exports to KML for Google Earth, GPX for GPS devices, and CSV for spreadsheets.

Frequently Asked Questions

How do I validate my GeoJSON file?

Use geojsonlint.com for instant browser-based validation against the RFC 7946 specification. For visual validation, paste your GeoJSON into geojson.io to see it rendered on a map. Programmatically, the @mapbox/geojsonhint npm package provides detailed error messages, while Python's geojson library offers validation methods. Common validation failures include wrong coordinate order, unclosed polygon rings, and missing required "type" fields.

What's the difference between GeoJSON and TopoJSON?

GeoJSON stores complete coordinates for each feature independently, making it simple but potentially redundant for adjacent polygons sharing borders. TopoJSON eliminates this redundancy by encoding topology, storing shared arcs once and referencing them. This typically reduces file size by 80% for polygon data. However, TopoJSON requires decoding back to GeoJSON before most mapping libraries can use it. For point data like Notion place exports, GeoJSON is more practical since there's no shared geometry to optimize.

Can I convert GeoJSON to KML or GPX?

Yes, GeoJSON converts readily to other formats. GDAL's ogr2ogr command handles conversions: ogr2ogr output.kml input.geojson or ogr2ogr -f GPX output.gpx input.geojson. Online tools like MyGeodata Converter and GPS Visualizer offer browser-based conversion. Note that GeoJSON properties may not map perfectly to KML or GPX fields, and styling information doesn't transfer. For Notion data, it's cleaner to export directly to your target format rather than converting.

Which format is best for web maps: GeoJSON or KML?

GeoJSON is definitively better for web maps. It parses natively in JavaScript, integrates with all modern mapping libraries without plugins, and follows web-friendly conventions. KML requires XML parsing, was designed for desktop applications like Google Earth, and carries unnecessary complexity for web use. The only reason to use KML on the web is if you're specifically embedding Google Earth or working with legacy systems that only accept KML.

How large can a GeoJSON file be before performance suffers?

Browser performance typically degrades noticeably above 5-10MB of GeoJSON or around 10,000 complex features. For large datasets, consider: simplifying geometry with tools like Mapshaper, using vector tiles instead of raw GeoJSON, implementing marker clustering for point data, or loading data progressively based on viewport. Mapbox GL JS handles larger datasets better than Leaflet due to WebGL rendering. For Notion exports, you're unlikely to hit these limits since databases rarely contain thousands of places.