GeoJSON Explained: Coordinates, Geometry Types, Validation, and Common Mapping Errors

Overview

GeoJSON is JSON with a defined structure for representing geographic features. A payload can describe a single location, a route, an area, a collection of geometries, or properties attached to any of those shapes. Most web mapping libraries can consume GeoJSON directly or with a small adapter.

The most important rule is coordinate order: GeoJSON uses longitude first, latitude second. A point near London, for example, can be represented as [-0.1276, 51.5072]. This differs from the latitude-longitude order commonly used in written descriptions, forms, and some mapping APIs. Treating [51.5072, -0.1276] as GeoJSON would place the point in a different location.

GeoJSON coordinates are expressed in decimal degrees for geographic data. A third value may be used for altitude or another position component, but applications should only rely on it when the producing and consuming systems agree on its meaning. Keep the payload consistent and avoid adding dimensions that your map library does not understand.

At the top level, GeoJSON commonly uses one of these object types:

• Point: one position.
• LineString: an ordered path made from two or more positions.
• Polygon: a closed area made from one exterior ring and optional interior rings.
• MultiPoint, MultiLineString, and MultiPolygon: collections of the corresponding geometry types.
• GeometryCollection: different geometry objects grouped together.
• Feature: a geometry plus application data in a properties object.
• FeatureCollection: an array of features, commonly used as a map layer or API response.

A minimal point feature looks like this:

{
  "type": "Feature",
  "properties": {
    "name": "Example location",
    "category": "office"
  },
  "geometry": {
    "type": "Point",
    "coordinates": [-0.1276, 51.5072]
  }
}

Checklist by scenario

When sending one marker

1. Set type to Feature if the marker needs a label, identifier, or other metadata.
2. Set geometry.type to Point.
3. Put the coordinate in [longitude, latitude] order.
4. Keep display values such as names and addresses in properties, not inside coordinates.
5. Confirm that both coordinate values are finite numbers, not numeric strings or missing values.

When drawing a route or boundary

1. Use LineString for a path where the final segment does not need to connect back to the first point.
2. Use Polygon for an area. Its linear ring must contain enough positions to form an area, and the final position should equal the first.
3. Check whether the source uses a closed boundary already. If it does not, close it deliberately rather than assuming the renderer will do so.
4. Inspect the path visually at a useful zoom level. Reversed coordinates can create a valid-looking JSON document that renders far from the intended place.

When returning several records from an API

1. Wrap records in a FeatureCollection with a features array.
2. Give each feature a stable id when the client needs selection, updates, or reconciliation.
3. Keep the shape of properties predictable. For example, use the same property name and type for every feature in a layer.
4. Return a valid JSON response with the appropriate content type and handle empty collections explicitly.
5. Test the response independently of the map, using a JSON formatter or a small validation script before investigating rendering code.

When importing data from another system

1. Identify the source coordinate reference system and confirm that the export is compatible with the GeoJSON expectations of your application.
2. Determine whether the source uses latitude-longitude order, a projected coordinate system, or another convention.
3. Normalize property names and numeric types at the ingestion boundary.
4. Reject, quarantine, or report malformed features rather than silently drawing partial data.

What to double-check

Geometry reference

Bounding boxes

A bbox can describe the extent of an object. For two-dimensional data, the usual form is [west, south, east, north]. In other words, it follows minimum longitude, minimum latitude, maximum longitude, and maximum latitude. Do not confuse a bounding box with a polygon: it is an extent for indexing, fitting the viewport, or quickly describing coverage, not necessarily the actual boundary.

Validation in JavaScript

Syntax validation and geographic validation are separate checks. JSON.parse() can confirm that text is valid JSON, but it cannot confirm that a polygon is closed or that a coordinate is in the expected order. A small application-level guard can catch common API errors before data reaches the map:

function isPosition(value) {
  return Array.isArray(value) &&
    value.length >= 2 &&
    Number.isFinite(value[0]) &&
    Number.isFinite(value[1]) &&
    value[0] >= -180 && value[0] <= 180 &&
    value[1] >= -90 && value[1] <= 90;
}

function isPointGeometry(geometry) {
  return geometry?.type === "Point" &&
    isPosition(geometry.coordinates);
}

function isFeatureCollection(value) {
  return value?.type === "FeatureCollection" &&
    Array.isArray(value.features);
}

This is not a complete GeoJSON validator. It is a useful first filter for an API client. For production ingestion, add checks for each geometry type, ring closure, required members, null geometries, and application-specific properties. If your project uses a schema or validation library, run it at the server boundary as well as during local development.

Common mistakes

• Swapping latitude and longitude: This is the most common cause of a valid payload rendering in the wrong country or ocean. Label variables as longitude and latitude instead of using ambiguous names such as x and y.
• Using strings for coordinates: ["-0.1276", "51.5072"] may pass through JSON but can fail numeric checks or produce inconsistent behavior. Convert and validate values before serialization.
• Leaving polygon rings open: A polygon boundary should repeat its first position as its final position. A renderer may try to repair this, but relying on repair makes data portability harder.
• Confusing a Feature with a geometry: A map method expecting a geometry may reject a complete Feature, while another method expects the full FeatureCollection. Check the input contract for the library you are using.
• Assuming every map uses the same data format: GeoJSON coordinates and provider-specific marker constructors may have different input shapes. Convert at one clear boundary and document it.
• Debugging the map before the response: Log the parsed object, inspect the network response, and format the JSON first. This separates malformed data from API-key, CORS, styling, or viewport problems. For related frontend failures, see the frontend API debugging checklist.

When GeoJSON is produced by a geocoding workflow, also verify which field contains the returned point and whether the provider's response must be transformed before it becomes a GeoJSON Feature. The JavaScript geocoding guide covers that integration boundary in more detail.

When to revisit

Revisit this checklist whenever you add a new data source, change a mapping library, alter an API response, or prepare a dataset for a seasonal planning cycle. It is especially useful before importing a new boundary file, changing database serialization, or replacing a geocoding provider.

Before release, run a small regression set containing one point, one line, one polygon, an empty FeatureCollection, and at least one intentionally invalid feature. Confirm coordinate order, property types, polygon closure, viewport fitting, and behavior when the geometry is null. Keep representative fixtures in version control so a library or workflow change can be tested against known data.

Finally, inspect the browser network panel and the rendered map together. If the JSON is correct but features are absent, investigate filtering, layer visibility, map bounds, projection assumptions, or client-side error handling. If the response itself is wrong, fix the transformation at the API boundary rather than adding special cases to every map component.