A geospatial API looks simple when the first endpoint returns a point on a map. Complexity arrives as soon as clients request areas, routes, multiple coordinate systems, large datasets, or updates over time. Small ambiguities—latitude before longitude, degrees mistaken for meters, a bounding box that crosses the antimeridian—can create errors that are difficult to detect visually and expensive to correct later.
The best first version is intentionally narrow. Choose a canonical representation, state its limits, provide predictable spatial filters, and attach enough metadata for clients to understand precision and freshness. This guide uses GeoJSON and resource-oriented HTTP patterns as a practical baseline, while highlighting the cases where a different representation is needed.
Define the resource before the geometry
A map feature should be a domain resource with a stable ID, lifecycle, attributes, and geometry—not just a loose coordinate object. A hydrant, trail, parcel, delivery zone, or sensor has business meaning that survives geometry edits. Keep the identifier stable when a point is corrected or a polygon is simplified. Include a revision or update time so clients can cache and reconcile changes.
Decide whether one resource can have multiple geometries. A building may have a footprint, label point, entrance locations, and a 3D model reference. Explicit roles are safer than a generic geometry array. Clients can request the representation they need without guessing which shape is authoritative.
Use GeoJSON deliberately
GeoJSON is a widely understood interchange format for points, line strings, polygons, multi-geometries, geometry collections, features, and feature collections. It works well for web APIs because geometry and properties can travel together in JSON. Use standard object types and avoid inventing look-alike fields that break existing parsers.
The coordinate order in standard GeoJSON is longitude, latitude, with optional elevation. This feels reversed to developers accustomed to saying “latitude and longitude,” so document it repeatedly and test it. Avoid accepting both orders based on heuristics; many values are valid in either position. Validation should reject coordinates outside allowed ranges and explain the expected order.
State the coordinate reference system
Standard GeoJSON uses geographic coordinates based on WGS 84. That is appropriate for interchange and global maps, but it is not ideal for every calculation. Distances and areas require geodesic methods or transformation to a suitable projected system. A server should not apply simple planar formulas to longitude and latitude as though they were meters.
If the API supports projected or local coordinates, make the format and frame explicit rather than overloading a GeoJSON field. You might expose a separate endpoint or representation with a named coordinate reference system. The important rule is that clients should never infer units from the magnitude of numbers.
Design bounding-box queries carefully
A bounding box is an efficient first spatial filter. A common query accepts west, south, east, north values and returns features that intersect the rectangle. State whether intersection means any overlap, centroid inside, or geometry fully contained. For large polygons, intersection can return features whose visible portion is small, so clients may need clipping or simplified output.
Global data introduces the antimeridian. A box where the western longitude is numerically greater than the eastern longitude may represent an area crossing 180 degrees rather than an invalid request. Decide whether to support that form, require two boxes, or use another geometry filter. Document maximum box size to prevent accidental world-scale queries.
Add radius, nearest, and polygon filters
After bounding boxes, common needs are “within a radius,” “nearest N,” and “intersects this polygon.” Radius queries need a center, distance, and unit. Nearest queries should define tie behavior and maximum search distance. Polygon filters need complexity limits and validation because arbitrary geometry can be expensive to process.
Return query context in the response: applied filters, units, result count, truncation, and continuation token. When results are sorted by distance, include the computed distance and method. Avoid making clients repeat calculations with a different Earth model and then wonder why ordering changes.
Pagination and spatial consistency
Offset pagination is unstable when features are added or moved between requests. Cursor pagination is usually safer. The cursor can encode a stable sort key, query signature, and snapshot or revision. For nearest-neighbor results, the continuation state may include the last distance and ID. Keep cursors opaque so the server can evolve its indexing strategy.
If a query must represent a consistent snapshot, say so and define how long that snapshot remains available. Real-time asset tracking may prefer fresh pages with possible duplication, while a compliance export may require a fixed dataset revision. The API should make this tradeoff explicit rather than leaving clients to infer it.
Precision, accuracy, and privacy
Coordinate precision is not the same as measurement accuracy. Six decimal places can imply sub-meter resolution even when the source location is only accurate to tens of meters. Include accuracy or quality fields when data comes from sensors. Preserve source precision internally, but consider whether responses need exact coordinates for the task.
Location can be personal or commercially sensitive. Reduce precision, aggregate, delay, or mask data when exact positions are unnecessary. Apply authorization to individual resources and fields, not just the collection endpoint. Logs and analytics should avoid storing full location payloads by default.
Indexing and performance
Spatial databases and indexes can accelerate intersection, containment, and proximity queries, but the API contract should not expose vendor-specific behavior. Normalize geometry on write, validate topology where required, and maintain indexes that match common query shapes. Large or complex geometry may need simplification, tiling, or precomputed representations.
Offer level-of-detail or field selection so a map viewport can request lightweight geometry while a detail page retrieves the full resource. Use cache validators and stable URLs for immutable tiles or revisions. Compression is especially valuable for coordinate-heavy payloads, but do not rely on compression to excuse unbounded responses.
Errors and validation
Good error responses identify the field, rejected value, rule, and expected format. Distinguish malformed geometry from valid geometry outside the service area. Report unsupported filters separately from empty results. For writes, validate coordinate order, ranges, polygon closure, geometry type, and domain-specific constraints before committing the resource.
Create fixtures for known cities, antimeridian cases, polar regions, empty geometries, self-intersections, and very small distances. Round-trip tests should confirm that stored and returned geometry remains within documented tolerances. Visual map inspection is useful, but it is not a substitute for numeric assertions.
Conclusion
A dependable geospatial API is built on explicit coordinate order, reference systems, query semantics, precision, and pagination. GeoJSON provides a strong interchange foundation, while bounding boxes and proximity filters cover many practical applications. The API becomes durable when it treats geometry as part of a versioned resource and communicates the assumptions behind every spatial result.
Versioning, edits, and geometry history
Geometry changes deserve the same discipline as other data changes. An edit can correct a survey, reflect construction, simplify a feature for display, or replace a predicted location with an observed one. Store the reason, source, editor, and effective time where the domain requires auditability. A revision ID lets clients submit conditional updates and detect that the feature changed after it was loaded.
Decide whether history is queryable. Some products need only the current shape and an updated timestamp. Others need “as of” queries, change feeds, or separate valid-time and transaction-time histories. Do not overload a modification date to represent all of these. If geometry is simplified for a response, keep that transformation distinct from a true revision of the source resource.
Bulk imports should be idempotent and resumable. Use source identifiers and batch IDs so a retry does not create duplicates. Validate the dataset boundary, coordinate reference system, and expected feature count before publishing a new version. A staging state lets teams inspect the map and run automated checks before the version becomes current.
First-release endpoint checklist
This small surface covers most map browsing and feature inspection workflows. More specialized operations—routing, raster analysis, geocoding, or editing topology—can be added as separate services once the core resource and coordinate contract is stable.
- Collection metadata with extent, update time, supported geometry, and query limits.
- Feature detail with stable ID, revision, geometry, properties, and source metadata.
- Bounding-box and radius filters with documented units and intersection semantics.
- Opaque cursor pagination and deterministic sorting.
- Conditional GET and conditional write support for efficient, safe clients.
- Validation errors that identify coordinate order, range, topology, or size problems.
- A compact representation option for map viewports and a full-detail option for inspection.