Geospatial APIs: PostGIS + FastAPI + spatial REST

The endpoint where space GIS meets the rest of the world is almost always a REST API. Someone downstream — another team, a paying customer, a frontend app — wants geospatial data over HTTP, with predictable URLs, ergonomic parameters, and JSON responses. This week you build that endpoint properly.

The shape of a spatial REST endpoint

The four query patterns that show up everywhere:

1. By ID — single feature by its identifier.
2. By bounding box — features inside a lon_min, lat_min, lon_max, lat_max box. Useful for map tiles.
3. By point and radius — features within radius_km of a lat, lon. Useful for near-me queries.
4. By polygon — features inside an arbitrary GeoJSON polygon. POST it as the request body.

Common parameters across all of them: time range, pagination, attribute filtering, sorting.

FastAPI plus PostGIS

The minimal stack:

from fastapi import FastAPI, Query
from sqlalchemy import create_engine, text

engine = create_engine("postgresql://...")
app = FastAPI(title="LaunchDetect API")

@app.get("/detections")
def detections(bbox: str | None = None, limit: int = 50):
    if bbox:
        lon_min, lat_min, lon_max, lat_max = map(float, bbox.split(","))
        sql = text("SELECT id, ST_AsGeoJSON(position) AS geom FROM detections "
                   "WHERE position && ST_MakeEnvelope(:l1,:l2,:l3,:l4,4326) "
                   "ORDER BY detected_at DESC LIMIT :lim")
        with engine.begin() as conn:
            rows = conn.execute(sql, dict(l1=lon_min,l2=lat_min,l3=lon_max,l4=lat_max,lim=limit)).all()
        return rows

OpenAPI for free

FastAPI auto-generates a full OpenAPI 3.0 specification from your function signatures and Pydantic models. Visit /docs for interactive Swagger UI, /redoc for ReDoc. Other teams can generate client SDKs in any language from the OpenAPI spec.

Pagination

Spatial endpoints often return many features. Two approaches:

• Offset pagination — easy to implement but degrades with large offsets and breaks if features are inserted or deleted between pages.
• Cursor pagination — a cursor parameter encodes the last item seen. Stable under writes, scales to any depth. Use the Link header per RFC 5988.

For high-traffic endpoints, cursor is the right default.

Caching

Spatial responses cache well. Set Cache-Control: public, max-age=60 on bbox queries. Use a CDN in front. For Lambda-fronted APIs, this can drop your origin load by 95 percent or more.

The lab

You will build a FastAPI app that wraps a PostGIS detections table and exposes the four endpoint patterns above. Returns GeoJSON. Documented via auto-generated OpenAPI at /docs. This is the architecture of launchdetect.com/space-data-api/ in production.