The reference implementation of the OGC API – Moving Features Standard over MobilityDB — a thin, compiled HTTP tier for clients that don't speak SQL or the PostgreSQL wire protocol.
MobilityAPI exposes MobilityDB collections of moving features over plain HTTP — for browser apps, mobile clients, microservices, and ETL / lakehouse pipelines. It is a thin tier: every temporal computation and (de)serialization runs inside MobilityDB itself (asMFJSON, atTime, tgeompointFromMFJSON, appendInstant). The server holds no MEOS — no cgo, no embedded library — so it stays small and stateless, and the database is the single source of truth.
- Streaming responses — a FeatureCollection is written row by row from a server-side cursor, so memory is bounded regardless of result size.
- Keyset pagination —
WHERE id > :afterwith OGCnextlinks, noOFFSET, constant cost through large collections. - Index-using filters —
bboxanddatetimepush to the MobilityDB GiST index;subtrajectoryclips withatTime. - Lakehouse export — a streaming
GET …/exportfeed (NDJSON, or?format=parquetwith the trajectory WKB plus a bbox/time sidecar) that DuckDB / MobilityDuck / Spark can ingest directly.
This Go server is the reference (production) implementation. A PyMEOS-based Python implementation is also available at MobilityAPI-Python.
HTTP client ──▶ MobilityAPI (Go · net/http + pgxpool) ──▶ MobilityDB / PostgreSQL
The tier translates between OGC API – Moving Features requests/responses and MobilityDB SQL; all geometry and temporal logic lives in the database.
| Method | Path | Description |
|---|---|---|
| GET | / · /api · /conformance | Landing page, OpenAPI document, conformance declaration |
| GET · POST · PUT · DELETE | /collections · /collections/{cid} | List, register, replace and delete collections (spatial + temporal extent) |
| GET | /collections/{cid}/items | Moving features, streamed and keyset-paged, with bbox / datetime / subtrajectory filters |
| GET · POST · PUT · DELETE | /collections/{cid}/items/{fid} | Read, replace and delete a moving feature; POST on the collection creates one from a MovingFeatureJSON body |
| GET · POST | /collections/{cid}/items/{fid}/tgsequence | Temporal geometry sequence (TemporalGeometrySequence); members are the trajectory's gap-separated sequences, each with a 1-based id; POST appends a temporally-disjoint member |
| DELETE | /collections/{cid}/items/{fid}/tgsequence/{tgid} | Delete a temporal primitive geometry (member sequence) by id |
| GET | /collections/{cid}/items/{fid}/tgsequence/{tgid}/{distance|velocity} | Derived kinematics on member {tgid}; acceleration returns 501 for the piecewise-constant motion model |
| GET · POST · DELETE | /collections/{cid}/items/{fid}/tproperties · /.../{pname} | User-supplied, stored temporal properties (TReal · TInt · TText · TBool), held as native MobilityDB temporal values |
| GET | /collections/{cid}/export | Lakehouse feed: NDJSON, or ?format=parquet |
| POST | /collections/{cid}/bulk | Bulk ingest of a fleet feed: GeoJSON / GeoParquet observations, each appended as one instant |
GET /export, PUT, and POST /bulk are opt-in extensions beyond the OGC conformance classes declared at GET /conformance. The surface is mapped against the OGC standard and the aistairc/mf-api reference in docs/mf-api-comparison.md.
- Go 1.25 or later
- PostgreSQL with the MobilityDB extension (and PostGIS)
go build -o mfapi .
MFAPI_DSN="postgres:///mydb?host=/var/run/postgresql&port=5432&user=me" ./mfapiThe server listens on :8088 by default. Configuration is by environment variable:
| Variable | Default | Meaning |
|---|---|---|
MFAPI_DSN | postgres:///mfapi_demo?host=/tmp&port=5432&user=esteban | MobilityDB connection string |
MFAPI_PORT | 8088 | Listen port |
MFAPI_MAXCONNS | 16 | Connection-pool size |
MFAPI_DEFAULT_LIMIT / MFAPI_MAX_LIMIT | 100 / 10000 | Page size defaults and ceiling |
MFAPI_EXPORT_LIMIT | 0 (unbounded) | Rows per export stream |
MFAPI_PARQUET_ROWGROUP | 1024 | Rows per Parquet row group (bounds export memory) |
go test ./...main.go— the server: routing, OGC request/response shaping, streaming and export.bulk.go— the bulk-ingest extension endpoint (GeoJSON / GeoParquet fleet feed).bench/— a comparison harness and results.tutorial/— a notebook walkthrough of the endpoints against the canonical AIS dataset.docs/— the OGC standard /aistairc/mf-apisurface comparison.
MobilityAPI is the HTTP / OGC layer of the MEOS ecosystem:
- MEOS (canonical C library) — the underlying type system and computations.
- MobilityDB · MobilityDuck · MobilitySpark — peer SQL surfaces over MEOS.
- Language bindings — PyMEOS, JMEOS, meos-rs, GoMEOS, MEOS.NET, MEOS.js.
A longer overview is at libmeos.org.
MobilityAPI is released under The PostgreSQL License.