thinair-co Geofences API

openapi: 3.2.0
info:
  title: ThinAir Geo Geofences API
  version: 1.0.0
  description: '## Overview


    Geocoding, autocomplete, structured search, place IDs, intersections, routing, distance matrix, isochrones, map matching, traffic, weather, and POI search — one API. REST and MCP consume the same ThinAir Geo service layer; this spec describes the REST surface.


    ## Base URL & authentication


    All endpoints live under `https://geo.thinair.co`. Authenticate with a bearer API key:


    ```bash

    curl "https://geo.thinair.co/v1/geocode?text=Pike Place Market Seattle" \

    -H "Authorization: Bearer ta_geo_…"

    ```


    ## Observability


    Every REST response carries a correlation pair (`X-Request-Id` / `X-Trace-Id`), a cache status (`X-Cache: HIT | HIT-EDGE | STALE | MISS | BYPASS`), and a per-stage timing family (`X-Auth-Ms`, `X-Quota-Ms`, `X-Upstream-Ms`, `X-Worker-Ms`, `X-Edge-Ms`, `X-Total-Ms`) — see components.headers for the full surface. Edge-cached lookups answer in single-digit milliseconds at the edge (verifiable via `X-Edge-Ms`); cold geocoding runs through the regional engine.


    ## Quota


    The daily-quota debit is write-behind on all API-key plans, so `X-Quota-Used` / `X-Quota-Remaining` are eventually consistent (typically within ~30 seconds); `GET /v1/quota` is the authoritative synchronous count.


    ## Enterprise access


    `https://geo.thinair.co` is the canonical public API and MCP surface. Azure API Management (APIM) is available as an enterprise access layer — private deployments, custom quota/SLA, VNET/private-link connectivity, subscription keys, and customer-side governance. APIM is an enterprise access layer. It does not own product behavior. All product behavior lives in the shared ThinAir Geo service layer consumed by REST, MCP, and APIM. APIM calls the same service layer (no separate business logic), preserves request/trace ids and ThinAir response shapes, and may add enterprise auth, quota, IP policy, logging, and private networking. Public documentation keeps `https://geo.thinair.co` as the canonical base URL; enterprise base URLs are issued per customer.'
servers:
- url: https://geo.thinair.co
security:
- bearerAuth: []
tags:
- name: Geofences
paths:
  /v1/geofences/contains:
    post:
      summary: Point-in-polygon containment test
      description: Test one or more points for containment inside a caller-supplied GeoJSON polygon (or MultiPolygon / Feature / FeatureCollection). Pure geometry — no upstream call, costs 0 quota units. Boundary points count as contained. Returns 400 when the polygon is structurally invalid.
      tags:
      - Geofences
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GeofenceContainsRequest'
            example:
              polygon:
                type: Polygon
                coordinates:
                - - - -95.4
                    - 29.7
                  - - -95.3
                    - 29.7
                  - - -95.3
                    - 29.8
                  - - -95.4
                    - 29.8
                  - - -95.4
                    - 29.7
              points:
              - lat: 29.75
                lon: -95.35
              - lat: 40
                lon: -100
      responses:
        '200':
          description: Containment results — one boolean per input point.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeofenceContainsResponse'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            X-Trace-Id:
              $ref: '#/components/headers/X-Trace-Id'
            X-Cache:
              $ref: '#/components/headers/X-Cache'
            X-Cache-Hit:
              $ref: '#/components/headers/X-Cache-Hit'
            X-Cache-Tier:
              $ref: '#/components/headers/X-Cache-Tier'
            X-Edge-Ms:
              $ref: '#/components/headers/X-Edge-Ms'
            X-Upstream-Ms:
              $ref: '#/components/headers/X-Upstream-Ms'
            X-Worker-Ms:
              $ref: '#/components/headers/X-Worker-Ms'
            X-Total-Ms:
              $ref: '#/components/headers/X-Total-Ms'
            X-Auth-Ms:
              $ref: '#/components/headers/X-Auth-Ms'
            X-Quota-Ms:
              $ref: '#/components/headers/X-Quota-Ms'
            X-Quota-Cost:
              $ref: '#/components/headers/X-Quota-Cost'
            X-Quota-Used:
              $ref: '#/components/headers/X-Quota-Used'
            X-Quota-Remaining:
              $ref: '#/components/headers/X-Quota-Remaining'
            X-Quota-Reset:
              $ref: '#/components/headers/X-Quota-Reset'
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-Session-Id:
              $ref: '#/components/headers/X-Session-Id'
            X-Edge-Location:
              $ref: '#/components/headers/X-Edge-Location'
            X-Data-Age-S:
              $ref: '#/components/headers/X-Data-Age-S'
        '400':
          description: Invalid request body or structurally-invalid polygon.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '429':
          description: Quota exceeded for this tenant.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      operationId: postV1GeofencesContains
      x-operation-id-source: derived
  /v1/geofences/validate:
    post:
      summary: Validate a GeoJSON polygon
      description: 'Check a caller-supplied GeoJSON polygon for well-formedness: ring closure, minimum vertex count, self-intersection, winding order (RFC 7946 right-hand rule), coordinate bounds, and complexity limits. Pure geometry — costs 0 quota units. A malformed polygon is NOT a 400; it returns `valid: false` with structured `errors`. Winding-order issues surface as `warnings` (containment is winding-agnostic).'
      tags:
      - Geofences
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GeofenceValidateRequest'
            example:
              polygon:
                type: Polygon
                coordinates:
                - - - -95.4
                    - 29.7
                  - - -95.3
                    - 29.7
                  - - -95.3
                    - 29.8
                  - - -95.4
                    - 29.8
                  - - -95.4
                    - 29.7
      responses:
        '200':
          description: 'Validation report. `valid: false` + errors on a malformed polygon (still a 200).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeofenceValidateResponse'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            X-Trace-Id:
              $ref: '#/components/headers/X-Trace-Id'
            X-Cache:
              $ref: '#/components/headers/X-Cache'
            X-Cache-Hit:
              $ref: '#/components/headers/X-Cache-Hit'
            X-Cache-Tier:
              $ref: '#/components/headers/X-Cache-Tier'
            X-Edge-Ms:
              $ref: '#/components/headers/X-Edge-Ms'
            X-Upstream-Ms:
              $ref: '#/components/headers/X-Upstream-Ms'
            X-Worker-Ms:
              $ref: '#/components/headers/X-Worker-Ms'
            X-Total-Ms:
              $ref: '#/components/headers/X-Total-Ms'
            X-Auth-Ms:
              $ref: '#/components/headers/X-Auth-Ms'
            X-Quota-Ms:
              $ref: '#/components/headers/X-Quota-Ms'
            X-Quota-Cost:
              $ref: '#/components/headers/X-Quota-Cost'
            X-Quota-Used:
              $ref: '#/components/headers/X-Quota-Used'
            X-Quota-Remaining:
              $ref: '#/components/headers/X-Quota-Remaining'
            X-Quota-Reset:
              $ref: '#/components/headers/X-Quota-Reset'
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-Session-Id:
              $ref: '#/components/headers/X-Session-Id'
            X-Edge-Location:
              $ref: '#/components/headers/X-Edge-Location'
            X-Data-Age-S:
              $ref: '#/components/headers/X-Data-Age-S'
        '400':
          description: Invalid request body (non-JSON or schema mismatch).
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '429':
          description: Quota exceeded for this tenant.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      operationId: postV1GeofencesValidate
      x-operation-id-source: derived
components:
  headers:
    X-Quota-Cost:
      description: Capability units this call debited.
      schema:
        type: string
    X-Worker-Ms:
      description: 'Worker-side overhead: total minus upstream (ms). Decomposes into X-Auth-Ms + X-Quota-Ms + unattributed residue (serialization, telemetry, routing).'
      schema:
        type: string
    X-Edge-Location:
      description: Edge location (IATA airport code) that served the request. Omitted when unavailable.
      schema:
        type: string
    X-RateLimit-Limit:
      description: Plan cap proxy (-1 = unlimited).
      schema:
        type: string
    X-Session-Id:
      description: Session correlation id grouping requests issued under one client session.
      schema:
        type: string
    X-Quota-Reset:
      description: ISO-8601 instant the daily counter rolls over.
      schema:
        type: string
    X-Cache-Hit:
      description: Legacy boolean cache signal (true|false). Prefer X-Cache.
      schema:
        type: string
    X-Trace-Id:
      description: Alias of X-Request-Id for tracing tooling that auto-detects the Trace-Id spelling.
      schema:
        type: string
    X-Data-Age-S:
      description: Age in seconds of the underlying data snapshot backing the response (e.g. a traffic observation). Only present on endpoints where data age is meaningful.
      schema:
        type: string
    X-Total-Ms:
      description: Equal to X-Edge-Ms; kept distinct per spec §6.
      schema:
        type: string
    X-Quota-Remaining:
      description: Daily limit minus used (-1 = unlimited). Eventually consistent (see X-Quota-Used); GET /v1/quota is authoritative.
      schema:
        type: string
    X-Quota-Ms:
      description: Synchronous quota work on the request path (ms). All API-key plans use a write-behind debit, so this reflects only the fast synchronous exhausted-flag check. The demo (Try-It) identity keeps the synchronous pre-flight peek + post-success debit (QuotaCounter round-trips).
      schema:
        type: string
    X-Edge-Ms:
      description: Total wall time the worker held the request (ms).
      schema:
        type: string
    X-Quota-Used:
      description: 'Units consumed in the current daily period. The debit is write-behind on all API-key plans: this value is eventually consistent (typically within ~30 seconds); GET /v1/quota is the authoritative synchronous count.'
      schema:
        type: string
    X-RateLimit-Remaining:
      description: Remaining headroom (-1 = unlimited).
      schema:
        type: string
    X-Auth-Ms:
      description: API-key validation time (ms). Present only on the ta_* api-key and demo-token paths; OAuth-JWT validation happens inside the auth library and is not measurable.
      schema:
        type: string
    X-Request-Id:
      description: Edge-generated request correlation id (req_*).
      schema:
        type: string
    X-Cache:
      description: 'Cache status: HIT (served from the cache without an upstream call), HIT-EDGE (served from the edge tier, no durable-store round-trip), STALE (served past its soft TTL while a background refresh runs), MISS (cacheable, went upstream), BYPASS (endpoint has no cache).'
      schema:
        type: string
        enum:
        - HIT
        - HIT-EDGE
        - STALE
        - MISS
        - BYPASS
    X-Cache-Tier:
      description: 'Serving cache tier, when reported: edge (edge tier), l0 (in-region cache), or kv (durable edge store).'
      schema:
        type: string
        enum:
        - edge
        - l0
        - kv
    X-Upstream-Ms:
      description: Wall time spent in engine round-trips (ms). Omitted on cache hits (no upstream call).
      schema:
        type: string
  schemas:
    GeofencePoint:
      type: object
      properties:
        lat:
          type: number
          minimum: -90
          maximum: 90
        lon:
          type: number
          minimum: -180
          maximum: 180
      required:
      - lat
      - lon
    GeofenceContainsRequest:
      type: object
      properties:
        polygon:
          $ref: '#/components/schemas/GeofencePolygon'
        points:
          type: array
          items:
            $ref: '#/components/schemas/GeofencePoint'
          maxItems: 1000
          description: Points to test for containment (up to 1000). { lat, lon } each.
      required:
      - polygon
      - points
    ProblemDetails:
      type: object
      properties:
        type:
          type: string
          format: uri
        title:
          type: string
        status:
          type: integer
        detail:
          type: string
        code:
          type: string
          description: Stable internal_code; see /docs/errors
        request_id:
          type: string
        instance:
          type: string
        retry_after_ms:
          type: integer
        upgrade_url:
          type: string
          description: Present on 429 (quota exceeded) and on 401 TRIAL_EXPIRED. Preselects the recommended plan and, when the caller's tenant is known, carries a short-lived token that upgrades the API key you are already using — no key swap and no config change after payment.
        suggested_upgrade:
          type:
          - string
          - 'null'
          description: Recommended next plan, or null on the top self-serve tier. 429 only.
        upgrade_cta:
          type: string
          description: One-line upgrade prompt. 429 only.
        upgrade_plans:
          type: array
          items:
            $ref: '#/components/schemas/UpgradePlan'
          description: Full self-serve plan menu. 429 only.
        next_step:
          type: string
          description: Prose instruction naming the same URL as upgrade_url. 429 only.
        usage:
          type: object
          properties:
            plan:
              type: string
            used:
              type: number
            limit:
              type: number
            period:
              type: string
            reset:
              type: string
              description: ISO 8601 instant the counter rolls over.
          required:
          - plan
          description: Where the cap stands. 429 only; counters are omitted when the denial has none.
        expired_at:
          type: string
          description: ISO 8601 instant the key stopped authenticating. TRIAL_EXPIRED only.
        plan:
          type: string
          description: Plan the expired key carried. TRIAL_EXPIRED only.
        quota:
          type: object
          properties:
            daily:
              type: number
            period:
              type: string
          required:
          - daily
          - period
          description: Daily allowance the expired key had; -1 = unlimited. TRIAL_EXPIRED only.
      required:
      - type
      - title
      - status
      - detail
      - code
      - request_id
      - instance
      description: RFC 7807 problem-details with ThinAir extensions (code, request_id, retry_after_ms). A 429 additionally carries upgrade_url, suggested_upgrade, upgrade_cta, upgrade_plans, next_step and usage; a 401 TRIAL_EXPIRED carries upgrade_url, expired_at, plan and quota.
    UpgradePlan:
      type: object
      properties:
        name:
          type: string
        price:
          type: string
          description: Display price, e.g. "$29/mo" or "custom".
        quota:
          type: string
          description: Display allowance, e.g. "10,000/day".
        note:
          type: string
        upgrade_url:
          type: string
          description: Checkout link for this specific plan. Carries the same plan preselect, in-place upgrade token and src attribution as the top-level upgrade_url.
      required:
      - name
      - price
      - quota
      - upgrade_url
      description: One self-serve plan offered on a 429.
    GeofenceContainsResponse:
      type: object
      properties:
        results:
          type: array
          items:
            type: boolean
          description: results[i] = true when points[i] is inside the polygon (boundary counts as inside).
        contained_count:
          type: integer
        point_count:
          type: integer
        warnings:
          type: array
          items:
            type: string
      required:
      - results
      - contained_count
      - point_count
    GeofencePolygon:
      anyOf:
      - type: object
        properties:
          type:
            type: string
            enum:
            - Polygon
          coordinates:
            type: array
            items:
              type: array
              items:
                type: array
                items:
                  type: number
                minItems: 2
                maxItems: 3
        required:
        - type
        - coordinates
      - type: object
        properties:
          type:
            type: string
            enum:
            - MultiPolygon
          coordinates:
            type: array
            items:
              type: array
              items:
                type: array
                items:
                  type: array
                  items:
                    type: number
                  minItems: 2
                  maxItems: 3
        required:
        - type
        - coordinates
      - type: object
        properties:
          type:
            type: string
            enum:
            - Feature
          geometry:
            type: object
            properties:
              type:
                type: string
            required:
            - type
            additionalProperties: {}
          properties:
            type:
            - object
            - 'null'
            additionalProperties: {}
        required:
        - type
        - geometry
      - type: object
        properties:
          type:
            type: string
            enum:
            - FeatureCollection
          features:
            type: array
            items:
              type: object
              properties:
                type:
                  type: string
                  enum:
                  - Feature
                geometry:
                  type: object
                  properties:
                    type:
                      type: string
                  required:
                  - type
                  additionalProperties: {}
                properties:
                  type:
                  - object
                  - 'null'
                  additionalProperties: {}
              required:
              - type
              - geometry
            maxItems: 100
        required:
        - type
        - features
      description: A GeoJSON Polygon / MultiPolygon geometry, a Feature wrapping one, or a FeatureCollection of them. Ring geometry is validated server-side (closure, winding, self-intersection, complexity limits).
    GeofenceValidateRequest:
      type: object
      properties:
        polygon:
          $ref: '#/components/schemas/GeofencePolygon'
      required:
      - polygon
    GeofenceValidateResponse:
      type: object
      properties:
        valid:
          type: boolean
        errors:
          type: array
          items:
            type: string
        warnings:
          type: array
          items:
            type: string
      required:
      - valid
      - errors
      - warnings
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer