Documentation
Standards & API
OGC API — Features Core + Part 3 Filtering, CQL2 text and JSON, keyset pagination, RFC 7807 errors, and one authenticated data path.
Conformance
The serving surface claims the OGC API — Features Core and Part 3 Filtering family. The verified six-URI subset is:
| Conformance class | URI |
|---|---|
| Core | http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/core |
| Filter | http://www.opengis.net/spec/ogcapi-features-3/1.0/conf/filter |
| Features Filter | http://www.opengis.net/spec/ogcapi-features-3/1.0/conf/features-filter |
| Basic CQL2 | http://www.opengis.net/spec/cql2/1.0/conf/basic-cql2 |
| CQL2 Text | http://www.opengis.net/spec/cql2/1.0/conf/cql2-text |
| CQL2 JSON | http://www.opengis.net/spec/cql2/1.0/conf/cql2-json |
The shipped service also advertises implemented extras ratified in ADR-0021. Official OGC certification is not claimed and is the final roadmap item.
Endpoint families
All paths are unversioned. All feature-data requests are authenticated and authorized through the gateway and the permission service. The public listing family is the only anonymous surface.
Serving
| Method | Path | Purpose |
|---|---|---|
| GET | / | Landing page and links |
| GET | /conformance | Conformance declaration |
| GET | /collections | Visible collections |
| GET | /collections/{collectionId} | Collection metadata |
| GET | /collections/{collectionId}/items | Features with bbox, datetime, filter |
| GET | /collections/{collectionId}/items/{featureId} | Single feature |
| GET | /collections/{collectionId}/queryables | Queryable properties |
| GET / POST | /search | Cross-collection search |
Discovery — public metadata
| Method | Path | Access |
|---|---|---|
| GET | /discovery/listings | Anonymous · metadata only · per-IP rate limit |
| GET | /discovery/listings/{collectionId} | Anonymous · metadata only |
Discovery — tenant scoped
| Method | Path | Result |
|---|---|---|
| GET | /discovery/available | Listed and accessible to the caller |
| GET | /discovery/offerings | Listed license offers not yet held |
| GET | /discovery/collections/{collectionId} | Scoped detail |
Authentication
| Caller | Credential | Notes |
|---|---|---|
| Public visitor | None | Only /discovery/listings. Metadata only; never feature data. |
| User | OIDC bearer token | Keycloak realms locateflow and locateflow-dev. |
| Machine | Tenant API key | Hashed at rest; shown once at creation. |
| Machine | OAuth2 client credentials | Keycloak client; secret shown once; revocation bound by token TTL. |
Example request
The environment variable name LOCATEFLOW_TOKEN is an example; the value is a tenant token and must never be committed or printed.
curl -s \
-H "Authorization: Bearer $LOCATEFLOW_TOKEN" \
"https://api.locateflow.xyz/collections?limit=10"Pagination
Feature and discovery pages use keyset cursors, not OFFSET. A response carries a next link when more data exists. The discovery family has its own cursor namespace; do not reuse a feature cursor across families.
Errors
Errors use application/problem+json (RFC 7807) with a stable code. Common statuses:
401— missing or invalid credential.403— authenticated but not permitted by the PDP.404— absent or deliberately opaque (no existence oracle).429— request quota or public rate limit exceeded; inspectRetry-After.503— a dependency is unavailable (for example, the identity provider during a machine-client operation).
Correlation
Send X-Correlation-Id to correlate a request with structured logs. If omitted, the gateway generates one and echoes it on the response.
Related
- Status & versions — what is actually released.
- Architecture — PEP/PDP request path.
- Public catalogue — metadata browsing.