thinair-co Conditions API

openapi: 3.2.0
info:
  title: ThinAir Geo Conditions 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: Conditions
paths:
  /v1/weather:
    get:
      description: Current conditions + optional multi-day forecast and severe-weather alerts for a coordinate pair or place name.
      summary: Weather - current conditions, forecast, and alerts
      tags:
      - Conditions
      parameters:
      - schema:
          type: number
          minimum: -90
          maximum: 90
        required: false
        name: lat
        in: query
      - schema:
          type: number
          minimum: -180
          maximum: 180
        required: false
        name: lon
        in: query
      - schema:
          type: string
          minLength: 1
          default: Houston, TX
          example: Houston, TX
          description: Free-text place name; geocoded server-side. Provide either lat+lon or location.
        required: false
        description: Free-text place name; geocoded server-side. Provide either lat+lon or location.
        name: location
        in: query
      - schema:
          type: string
          enum:
          - imperial
          - metric
          example: imperial
          description: 'Temperature/wind units (default: imperial).'
        required: false
        description: 'Temperature/wind units (default: imperial).'
        name: units
        in: query
      - schema:
          type:
          - boolean
          - 'null'
          example: false
          description: Include multi-day hourly forecast.
        required: false
        description: Include multi-day hourly forecast.
        name: include_forecast
        in: query
      - schema:
          type: integer
          minimum: 1
          maximum: 16
          example: 5
          description: Forecast horizon in days (1-16, default 5).
        required: false
        description: Forecast horizon in days (1-16, default 5).
        name: forecast_days
        in: query
      - schema:
          type:
          - boolean
          - 'null'
          example: true
          description: 'Include severe-weather alerts (default: true).'
        required: false
        description: 'Include severe-weather alerts (default: true).'
        name: include_alerts
        in: query
      - schema:
          type:
          - boolean
          - 'null'
          example: false
          description: Include minute-by-minute precipitation for the next 60 minutes.
        required: false
        description: Include minute-by-minute precipitation for the next 60 minutes.
        name: include_minutely
        in: query
      responses:
        '200':
          description: Weather observations and forecasts.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WeatherResponse'
          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: Validation error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '429':
          description: Quota exceeded.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '502':
          description: Weather provider unavailable.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '504':
          description: Weather provider timed out.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      operationId: getV1Weather
      x-operation-id-source: derived
  /v1/traffic:
    get:
      description: 'Live traffic conditions and speed aggregates at a coordinate. Coverage is concentrated in major US metros; outside coverage areas the response carries `coverage: false`.'
      summary: Live traffic - speed and congestion for a point
      tags:
      - Conditions
      parameters:
      - schema:
          type: number
          minimum: -90
          maximum: 90
          description: Latitude in decimal degrees, WGS84.
          example: 29.7604
        required: true
        description: Latitude in decimal degrees, WGS84.
        name: lat
        in: query
      - schema:
          type: number
          minimum: -180
          maximum: 180
          description: Longitude in decimal degrees, WGS84.
          example: -95.3698
        required: true
        description: Longitude in decimal degrees, WGS84.
        name: lon
        in: query
      - schema:
          type: string
          enum:
          - miles
          - kilometers
          example: miles
          description: Speed units. Auto-detected from location (mph in US/UK/Myanmar/Liberia, km/h elsewhere) when omitted. Accepts 'km'/'mi' as aliases for 'kilometers'/'miles'.
        required: false
        description: Speed units. Auto-detected from location (mph in US/UK/Myanmar/Liberia, km/h elsewhere) when omitted. Accepts 'km'/'mi' as aliases for 'kilometers'/'miles'.
        name: units
        in: query
      responses:
        '200':
          description: Traffic conditions for the queried point.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrafficResponse'
          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: Validation error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '429':
          description: Quota exceeded.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '503':
          description: 'Live traffic capacity temporarily exhausted (code BACKPRESSURE). Retryable: `retry_after_ms` and the `Retry-After` header point at the next 00:00 UTC reset. Not charged.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      operationId: getV1Traffic
      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-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-RateLimit-Remaining:
      description: Remaining headroom (-1 = unlimited).
      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:
    TrafficResponse:
      type: object
      properties:
        lat:
          type: number
        lon:
          type: number
        coverage:
          type: boolean
        coverage_reason:
          type: string
          enum:
          - disabled
          - unavailable
        current_speed:
          type:
          - number
          - 'null'
        free_flow_speed:
          type:
          - number
          - 'null'
        ratio_pct:
          type:
          - number
          - 'null'
        units:
          type: string
        segments:
          type: array
          items:
            type: object
            additionalProperties: {}
        segment_count:
          type: number
        closures:
          type: number
        congestion:
          type: string
        meta:
          type: object
          properties:
            upstream_ms:
              type: number
            feature_count:
              type: number
            cacheHit:
              type: boolean
          required:
          - upstream_ms
          - feature_count
        upstream_error:
          type:
          - string
          - 'null'
      required:
      - lat
      - lon
      - current_speed
      - free_flow_speed
      - ratio_pct
      - units
      - segments
      - segment_count
      - closures
      - congestion
      - meta
      description: 'Pass-through of the typed TrafficResult. `coverage: false` means no live data was returned; `coverage_reason` names the cause when it is known to be something other than the location (`disabled`, `unavailable`) and is absent for a genuine coverage gap.'
    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.
    WeatherResponse:
      type: object
      properties:
        location:
          type: object
          properties:
            lat:
              type: number
            lon:
              type: number
            label:
              type: string
          required:
          - lat
          - lon
        units:
          type: string
          enum:
          - imperial
          - metric
        current:
          type: object
          additionalProperties: {}
        forecast:
          type: array
          items:
            type: object
            additionalProperties: {}
        forecast_days:
          type: number
        alerts:
          type: array
          items:
            type: object
            additionalProperties: {}
        alerts_error:
          type: string
        minutely_precipitation:
          type: array
          items:
            type: object
            additionalProperties: {}
        minutely_error:
          type: string
        source:
          type: string
        meta:
          type: object
          properties:
            upstream_ms:
              type: number
            feature_count:
              type: number
            cacheHit:
              type: boolean
          required:
          - upstream_ms
          - feature_count
        upstream_error:
          type:
          - string
          - 'null'
      required:
      - location
      - units
      - current
      - source
      - meta
      description: Pass-through of the typed WeatherResult. Field set varies with include_* flags.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer