{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/stadia-maps/refs/heads/main/json-schema/stadia-maps-location-schema.json",
  "title": "Stadia Maps Location",
  "description": "A geocoded location result from the Stadia Maps Pelias geocoding engine, returned by search, reverse geocoding, autocomplete, and place detail endpoints.",
  "type": "object",
  "properties": {
    "geocoding": {
      "type": "object",
      "description": "Metadata about the geocoding engine and query",
      "properties": {
        "version": { "type": "string", "description": "Pelias geocoder version" },
        "attribution": { "type": "string", "description": "Data attribution URL" },
        "query": {
          "type": "object",
          "description": "Echo of the query parameters"
        },
        "engine": {
          "type": "object",
          "description": "Geocoding engine details",
          "properties": {
            "name": { "type": "string" },
            "author": { "type": "string" },
            "version": { "type": "string" }
          }
        }
      }
    },
    "type": {
      "type": "string",
      "description": "GeoJSON feature collection type",
      "enum": ["FeatureCollection"]
    },
    "features": {
      "type": "array",
      "description": "Array of GeoJSON Feature objects representing geocoded locations",
      "items": {
        "$ref": "#/$defs/Feature"
      }
    },
    "bbox": {
      "type": "array",
      "description": "Bounding box of the result set [minLon, minLat, maxLon, maxLat]",
      "items": { "type": "number" },
      "minItems": 4,
      "maxItems": 4
    }
  },
  "required": ["type", "features"],
  "$defs": {
    "Feature": {
      "type": "object",
      "description": "A single geocoded place as a GeoJSON Feature",
      "properties": {
        "type": { "type": "string", "enum": ["Feature"] },
        "geometry": {
          "type": "object",
          "description": "GeoJSON Point geometry",
          "properties": {
            "type": { "type": "string", "enum": ["Point"] },
            "coordinates": {
              "type": "array",
              "description": "Longitude and latitude [lon, lat]",
              "items": { "type": "number" },
              "minItems": 2,
              "maxItems": 2
            }
          },
          "required": ["type", "coordinates"]
        },
        "properties": {
          "$ref": "#/$defs/PlaceProperties"
        },
        "bbox": {
          "type": "array",
          "items": { "type": "number" }
        }
      },
      "required": ["type", "geometry", "properties"]
    },
    "PlaceProperties": {
      "type": "object",
      "description": "Properties of a geocoded place",
      "properties": {
        "id": { "type": "string", "description": "Unique place identifier (GID)" },
        "gid": { "type": "string", "description": "Global place identifier" },
        "layer": {
          "type": "string",
          "description": "Place type layer",
          "enum": ["venue", "address", "street", "neighbourhood", "locality", "borough", "localadmin", "county", "macrocounty", "region", "macroregion", "country", "postalcode"]
        },
        "source": { "type": "string", "description": "Data source (openstreetmap, openaddresses, geonames, whosonfirst)" },
        "source_id": { "type": "string", "description": "Source-specific identifier" },
        "name": { "type": "string", "description": "Primary display name" },
        "housenumber": { "type": "string", "description": "Street number" },
        "street": { "type": "string", "description": "Street name" },
        "postalcode": { "type": "string", "description": "Postal / ZIP code" },
        "confidence": {
          "type": "number",
          "minimum": 0,
          "maximum": 1,
          "description": "Confidence score for the geocoding result (0-1)"
        },
        "match_type": {
          "type": "string",
          "description": "Type of match returned",
          "enum": ["exact", "interpolated", "fallback"]
        },
        "accuracy": {
          "type": "string",
          "description": "Accuracy level of the coordinate",
          "enum": ["point", "centroid", "rooftop"]
        },
        "country": { "type": "string", "description": "Country name" },
        "country_gid": { "type": "string", "description": "Country GID" },
        "country_a": { "type": "string", "description": "ISO 3166-1 alpha-3 country code" },
        "region": { "type": "string", "description": "Region or state name" },
        "region_gid": { "type": "string", "description": "Region GID" },
        "region_a": { "type": "string", "description": "Region abbreviation (e.g., CA)" },
        "county": { "type": "string", "description": "County name" },
        "county_gid": { "type": "string", "description": "County GID" },
        "locality": { "type": "string", "description": "City or town name" },
        "locality_gid": { "type": "string", "description": "Locality GID" },
        "neighbourhood": { "type": "string", "description": "Neighbourhood name" },
        "label": { "type": "string", "description": "Full formatted address label for display" },
        "addendum": {
          "type": "object",
          "description": "Source-specific additional data"
        }
      },
      "required": ["name", "label"]
    }
  }
}