LocateResponse

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/thinair-co/json-schema/thinair-co-locate-response-schema.json",
  "title": "LocateResponse",
  "x-generated": "2026-10-30",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/geo-thinair-co-openapi.json#/components/schemas/LocateResponse",
  "type": "object",
  "properties": {
    "summary": {
      "type": "string",
      "description": "Human/LLM-friendly summary of the road match."
    },
    "matched": {
      "type": "boolean"
    },
    "road_status": {
      "type": "string",
      "enum": [
        "matched",
        "no_road_nearby",
        "unavailable"
      ],
      "description": "Why `road` is what it is. `matched` - a routable road was found. `no_road_nearby` - the road lookup answered and found no routable road for this travel profile (a real answer; may be cached). `unavailable` - the road lookup could not be answered right now; this says nothing about the point, `matched` is `false`, `road` is `null`, `retryable` is `true`, and the result is never cached. The timezone and elevation fields are still resolved."
    },
    "retryable": {
      "type": "boolean",
      "description": "Present and `true` only when `road_status` is `unavailable`: the same request may succeed shortly."
    },
    "location": {
      "type": "object",
      "properties": {
        "lat": {
          "type": "number"
        },
        "lon": {
          "type": "number"
        }
      },
      "required": [
        "lat",
        "lon"
      ]
    },
    "road": {
      "$ref": "#/$defs/LocateRoad"
    },
    "timezone": {
      "type": [
        "string",
        "null"
      ],
      "description": "IANA timezone name for the point (e.g. `America/Los_Angeles`), resolved by point-in-polygon against published timezone boundaries. Null unless `timezone_status` is `resolved` — an absent timezone is reported rather than an estimated one. Contains information from timezone-boundary-builder, which is made available under the Open Database License (ODbL) v1.0. Timezone boundaries © OpenStreetMap contributors. US legal-zone cross-check: U.S. Department of Transportation, Bureau of Transportation Statistics (public domain)."
    },
    "timezone_status": {
      "type": "string",
      "enum": [
        "resolved",
        "boundary_ambiguous",
        "source_conflict",
        "not_covered",
        "unavailable"
      ],
      "description": "Why `timezone` is what it is. `resolved` — exactly one zone contains the point, clear of every boundary. `boundary_ambiguous` — on or within the documented boundary tolerance of an edge, or claimed by two zones. `source_conflict` — the boundary data and the US legal-zone layer disagree here. `not_covered` — no zone polygon contains the point. `unavailable` — no verified boundary artifact is active. Only `resolved` carries a name."
    },
    "timezone_artifact_version": {
      "type": [
        "string",
        "null"
      ],
      "description": "Version of the timezone boundary artifact that produced this answer. Changes when the data is promoted, and participates in this endpoint's cache identity so an answer cannot outlive the data it came from."
    },
    "elevation_m": {
      "type": [
        "number",
        "null"
      ],
      "description": "Ground elevation in metres. Non-null only when `include_elevation=true` AND terrain data is available; `null` otherwise."
    },
    "elevation_ft": {
      "type": [
        "number",
        "null"
      ]
    },
    "grade_pct": {
      "type": [
        "number",
        "null"
      ],
      "description": "Road grade at the point, percent. Reserved — `null` until an elevation-enhanced road network or verified post-processing are live."
    },
    "geojson": {
      "$ref": "#/$defs/LocateGeoJson"
    },
    "warnings": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "meta": {
      "$ref": "#/$defs/LocateMeta"
    },
    "upstream_error": {
      "type": [
        "string",
        "null"
      ]
    }
  },
  "required": [
    "summary",
    "matched",
    "road_status",
    "location",
    "road",
    "timezone",
    "timezone_status",
    "timezone_artifact_version",
    "elevation_m",
    "elevation_ft",
    "grade_pct",
    "geojson",
    "warnings",
    "meta"
  ],
  "$defs": {
    "LocateGeoJson": {
      "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",
                    "enum": [
                      "Point"
                    ]
                  },
                  "coordinates": {
                    "type": "array",
                    "prefixItems": [
                      {
                        "type": "number"
                      },
                      {
                        "type": "number"
                      }
                    ]
                  }
                },
                "required": [
                  "type",
                  "coordinates"
                ]
              },
              "properties": {
                "type": "object",
                "additionalProperties": {}
              }
            },
            "required": [
              "type",
              "geometry",
              "properties"
            ]
          }
        }
      },
      "required": [
        "type",
        "features"
      ]
    },
    "LocateMeta": {
      "type": "object",
      "properties": {
        "upstream_ms": {
          "type": "number"
        },
        "feature_count": {
          "type": "number"
        },
        "cacheHit": {
          "type": "boolean",
          "description": "True when the result was served from the edge grid cache (no upstream call)."
        },
        "units": {
          "type": "string",
          "enum": [
            "imperial",
            "metric"
          ]
        },
        "include_elevation": {
          "type": "boolean"
        },
        "degraded": {
          "type": "boolean",
          "description": "Present and `true` only when `road_status` is `unavailable`: the road lookup could not be answered, so the result carries the timezone (and elevation, when requested and available) but no road information."
        },
        "elevation_source": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "terrain",
            null
          ],
          "description": "Provenance of `elevation_m` — `terrain` when sampled from terrain/DEM data, or `null` when unavailable."
        }
      },
      "required": [
        "upstream_ms",
        "feature_count",
        "units",
        "include_elevation",
        "elevation_source"
      ]
    },
    "LocateRoad": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "name": {
          "type": [
            "string",
            "null"
          ]
        },
        "road_class": {
          "type": [
            "string",
            "null"
          ]
        },
        "speed_limit_kph": {
          "type": [
            "number",
            "null"
          ]
        },
        "speed_limit_mph": {
          "type": [
            "number",
            "null"
          ]
        },
        "bearing": {
          "type": [
            "number",
            "null"
          ]
        },
        "distance_m": {
          "type": [
            "number",
            "null"
          ]
        },
        "distance_ft": {
          "type": [
            "number",
            "null"
          ]
        },
        "side_of_street": {
          "type": "string",
          "enum": [
            "left",
            "right",
            "unknown"
          ]
        },
        "truck_legal": {
          "type": [
            "boolean",
            "null"
          ]
        },
        "has_toll": {
          "type": "boolean"
        },
        "has_ferry": {
          "type": "boolean"
        },
        "has_highway": {
          "type": "boolean"
        },
        "bridge": {
          "type": "boolean"
        },
        "tunnel": {
          "type": "boolean"
        }
      },
      "required": [
        "name",
        "road_class",
        "speed_limit_kph",
        "speed_limit_mph",
        "bearing",
        "distance_m",
        "distance_ft",
        "side_of_street",
        "truck_legal",
        "has_toll",
        "has_ferry",
        "has_highway",
        "bridge",
        "tunnel"
      ]
    }
  }
}