AR-1004 · API Specification

Developer API

A public, read-only API that returns registered location preferences as GeoJSON, so drone, AR, and UTM planning tools can surface them for an operating area at planning time.

Part of the Airspace Registry document family: Charter (AR-0001) · Architecture Specification (AR-1000) · API Specification (AR-1004, this page).

Base URL

https://airspaceregistry.org/api/v1

No API key required. CORS is open. Responses are cacheable (60s). Use of the API and site is governed by the Terms of Use.

Live demo endpoints — three ways to query

The three coverage demos (/demo) are backed by real, callable endpoints — not screenshots. They expose the same read contract at three scales: an area, a point, and a point in time. Every request below is live.

1 · Area — “give me everything here”

GET https://airspaceregistry.org/api/v1/demo/preferences?region=raleigh

Bulk GeoJSON for a whole region — for GIS ingestion and map overlays. Regions: raleigh, times_square, sofi_stadium.

2 · Point — “what’s true right here?”

GET https://airspaceregistry.org/api/v1/demo/resolve?lat=35.8776&lon=-78.7875

Resolves the applicable registry preference at an exact coordinate (point-in-polygon; the most specific footprint wins). Informational metadata only.

{
  "resolved": true,
  "location": "Raleigh-Durham International Airport",
  "kind": "airport",
  "drone_preference": "sensitive",
  "ar_preference": "coordinate",
  "categories": [],
  "advisory": "Drone-sensitive location — major airport nearby.",
  "temporal_rule": null,
  "window_active": null
}

3 · Point in time — “what’s true here at this moment?”

GET https://airspaceregistry.org/api/v1/demo/resolve
  ?lat=33.9535&lon=-118.3392
  &datetime=2027-02-14T18:30:00-08:00

The same point at SoFi Stadium, queried during Super Bowl LXI, shows the registry’s drone-sensitive event window active, and when it ends:

{
  "resolved": true,
  "location": "SoFi Stadium",
  "drone_preference": "sensitive",
  "ar_preference": "commercial",
  "advisory": "Drone-sensitive during scheduled major events at this venue.",
  "temporal_rule": { "active": true, "event": "Super Bowl LXI", "end": "2027-02-15T03:30:00.000Z" },
  "window_active": true,
  "effective_until": "2027-02-15T03:30:00.000Z",
  "note": "A registered drone-sensitive time window is active at the queried time."
}

Query that same coordinate off-event and it returns window_active: false plus the next_window — same place, different context by the minute.

Together these show bulk retrieval, point lookup, and time-scoped context. This is an informational metadata layer a planning tool can surface to an operator — the preference/context that isn’t in existing feeds. It does not return a go/no-go and is not permissions; any operational decision stays with the operator’s own systems. The resolve endpoint runs over the demo dataset; the community /preferences endpoints below use the same shapes over live registry data.

Reading the results

• resolved: false is a valid answer, not an error — like a directory lookup that returns no record. It means no footprint contains that point, so this informational layer carries nothing there. The demos model three areas and sample their footprints, so streets, gaps, and points elsewhere correctly return no record; the response’s note says which case applies.
• Always include a timezone offset in datetime (e.g. -08:00). A naked datetime is parsed as UTC and can miss a local-time window; the response returns a warning when that happens.
• Region ids use underscores: raleigh, times_square, sofi_stadium.

Query preferences in an area

GET /preferences

Filter by a bounding box or a point + radius:

Example — everything within 10 km of lower Manhattan:

GET https://airspaceregistry.org/api/v1/preferences?lat=40.7128&lng=-74.0060&radius_km=10

Example — look up a place by its stable Overture GERS ID (no coordinates needed):

GET https://airspaceregistry.org/api/v1/preferences?gers_id=08b2a3a14e1f41b2bc6d88f6a964a2e5

Look up one entry

GET /preferences/{location_id}   e.g. /preferences/asr_AbC123

Response (GeoJSON)

{
  "type": "FeatureCollection",
  "schema_version": "1.0",
  "standards": { "geopose": "OGC GeoPose 1.0 (Basic-YPR)" },
  "generated_at": "2026-06-29T21:00:00.000Z",
  "count": 1,
  "disclaimer": "Preferences are informational and voluntary ...",
  "features": [
    {
      "type": "Feature",
      "geometry": { "type": "Point", "coordinates": [-74.0060, 40.7128] },
      "properties": {
        "location_id": "asr_AbC123",
        "title": "Example rooftop",
        "drone_preference": "sensitive",
        "ar_preference": "welcome",
        "source": "community_registry",
        "verified": false,
        "verification_status": "unverified",
        "altitude_floor_ft": 0,
        "altitude_ceiling_ft": 400,
        "altitude_floor_m": 0,
        "altitude_ceiling_m": 122,
        "radius_m": 50,
        "address": { "city": "New York", "state": "NY", "country": "USA" },
        "last_updated": "2026-06-29T18:30:00.000Z",
        "geopose": {
          "position": { "lat": 40.7128, "lon": -74.0060, "h": 0 },
          "angles": { "yaw": 0, "pitch": 0, "roll": 0 }
        }
      }
    }
  ]
}

Field reference

Fields by context class

Every field on this page belongs to one of the five context classes defined in the Architecture Specification (AR-1000) — the taxonomy that organizes a Location Profile. The classes organize the fields; this specification defines them.

Open AR standard — OGC GeoPose

Every anchor carries a geopose in the OGC GeoPose 1.0 Basic-YPR encoding — the open standard for geospatially anchoring content — so AR and spatial-computing clients (including the Open AR Cloud stack) can consume a place’s preferences directly, without a bespoke shape. Each response also advertises the standard in a top-level standards object.

"geopose": {
  "position": { "lat": 40.7128, "lon": -74.0060, "h": 0 },   // h = altitude floor (m)
  "angles":   { "yaw": 0, "pitch": 0, "roll": 0 }             // a place preference has no orientation
}

The pose locates the anchor; orientation is identity because a location preference has no inherent facing. The /resolve endpoint returns the GeoPose of the queried point alongside the applicable preference.

Open AR Cloud — Spatial Content Discovery

GET /api/v1/scd?bbox=&|lat=&lng=[&radius_km=] publishes the registry’s preferences at a location as Open AR Cloud OSCP Spatial Content Records — so an AR client can discover a place’s preference through the open spatial stack, not just our API. Returned with media type application/vnd.oscp+json; version=1.0, location-scoped (never a full read).

{
  "id": "asr_AbC123",
  "type": "scr",
  "tenant": "airspaceregistry.org",
  "content": {
    "id": "asr_AbC123",
    "type": "airspace_preference",
    "title": "Example venue",
    "geopose": {
      "position":   { "lon": -74.006, "lat": 40.7128, "h": 0 },
      "quaternion": { "x": 0, "y": 0, "z": 0, "w": 1 }
    },
    "refs": [
      { "contentType": "application/geo+json", "url": ".../api/v1/preferences/asr_AbC123" },
      { "contentType": "text/html",            "url": ".../claim?id=AbC123" }
    ],
    "definitions": [
      { "type": "drone_preference", "value": "sensitive" },
      { "type": "ar_preference",    "value": "coordinate" }
    ]
  }
}

Resolve a point — coverage layers

GET /api/v1/resolve?lat=&lng=[&datetime=] answers “what preference applies right here?” by walking two layers in order of precedence:

GET /api/v1/resolve?lat=35.7725&lng=-78.678
{
  "resolved": true,
  "layer": "type_default",
  "is_default": true,          // a suggestion by place type — not owner-set
  "claimable": true,
  "location": "Skema Campus @ NC State",
  "bucket": "schools",
  "drone_preference": "sensitive",
  "ar_preference": "coordinate",
  "distance_m": 0,
  "geopose": { "position": { "lat": 35.7725, "lon": -78.678, "h": 0 }, "angles": { "yaw": 0, "pitch": 0, "roll": 0 } },
  "note": "No owner has set a preference here. This is a suggested default …"
}

Optional metadata (next layer)

Records may optionally carry activity categories, a schedule window, and a temporary condition — evolving from a static preference into richer machine-readable metadata for a place. All fields are optional and default to empty.

"metadata_categories": ["drone_filming", "ar_content"],
"temporal_rule": {
  "enabled": true,
  "start_datetime": "2026-07-04T17:00:00Z",   // may be null (open "until")
  "end_datetime": "2026-07-04T22:00:00Z"       // may be null (open "from")
},
"temporary_condition": { "type": "event", "description": "Large public gathering" }

These fields remain informational and advisory — not enforceable and not permissions.

How to use it (operators)

At mission planning, query your operating area, surface any returned preferences to the pilot, and use them for courtesy coordination and conflict reduction. A returned preference is not enforceable and is not a permission; it is a communication signal from the place to the operator.

Roadmap

Planned, not yet available: eVTOL preferences alongside drone and AR, a richer per-activity category taxonomy, parcel-level snapping, and webhook subscriptions for changes within an operating area. Interested in a pilot or integration? ops@airspaceregistry.org.