{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/pelias/main/json-schema/geocoding-response.json",
  "title": "Pelias Geocoding Response",
  "description": "GeoJSON FeatureCollection returned by all Pelias geocoding endpoints",
  "type": "object",
  "required": ["geocoding", "type", "features"],
  "properties": {
    "geocoding": {
      "type": "object",
      "description": "Metadata about the geocoding request and engine",
      "properties": {
        "version": { "type": "string", "example": "1.0" },
        "attribution": { "type": "string", "format": "uri" },
        "query": {
          "type": "object",
          "description": "Parsed query parameters echoed back",
          "additionalProperties": true
        },
        "engine": {
          "type": "object",
          "properties": {
            "name": { "type": "string" },
            "author": { "type": "string" },
            "version": { "type": "string" }
          }
        },
        "timestamp": {
          "type": "integer",
          "description": "Unix timestamp in milliseconds"
        },
        "errors": {
          "type": "array",
          "items": { "type": "string" },
          "description": "List of error messages if the request failed"
        }
      }
    },
    "type": {
      "type": "string",
      "const": "FeatureCollection"
    },
    "features": {
      "type": "array",
      "description": "List of geocoded place features",
      "items": {
        "type": "object",
        "required": ["type", "geometry", "properties"],
        "properties": {
          "type": { "type": "string", "const": "Feature" },
          "geometry": {
            "type": "object",
            "required": ["type", "coordinates"],
            "properties": {
              "type": { "type": "string", "const": "Point" },
              "coordinates": {
                "type": "array",
                "description": "[longitude, latitude] per GeoJSON spec",
                "items": { "type": "number" },
                "minItems": 2,
                "maxItems": 2
              }
            }
          },
          "properties": {
            "type": "object",
            "properties": {
              "id": { "type": "string" },
              "gid": {
                "type": "string",
                "description": "Pelias Global Identifier: source:layer:id",
                "pattern": "^[a-z]+:[a-z]+:.+$"
              },
              "layer": {
                "type": "string",
                "enum": [
                  "venue", "address", "street", "neighbourhood", "borough",
                  "localadmin", "locality", "county", "macrocounty", "region",
                  "macroregion", "country", "coarse", "postalcode"
                ]
              },
              "source": {
                "type": "string",
                "enum": ["openstreetmap", "openaddresses", "whosonfirst", "geonames"]
              },
              "source_id": { "type": "string" },
              "name": { "type": "string" },
              "label": { "type": "string" },
              "confidence": {
                "type": "number",
                "minimum": 0,
                "maximum": 1
              },
              "distance": {
                "type": "number",
                "description": "Distance in km from query point (reverse geocoding only)"
              },
              "country": { "type": "string" },
              "country_gid": { "type": "string" },
              "country_a": {
                "type": "string",
                "description": "ISO 3166-1 alpha-3 country code",
                "minLength": 2,
                "maxLength": 3
              },
              "macroregion": { "type": "string" },
              "macroregion_gid": { "type": "string" },
              "region": { "type": "string" },
              "region_gid": { "type": "string" },
              "region_a": { "type": "string" },
              "county": { "type": "string" },
              "county_gid": { "type": "string" },
              "localadmin": { "type": "string" },
              "localadmin_gid": { "type": "string" },
              "locality": { "type": "string" },
              "locality_gid": { "type": "string" },
              "borough": { "type": "string" },
              "borough_gid": { "type": "string" },
              "neighbourhood": { "type": "string" },
              "neighbourhood_gid": { "type": "string" },
              "postalcode": { "type": "string" },
              "housenumber": { "type": "string" },
              "street": { "type": "string" },
              "categories": {
                "type": "array",
                "items": { "type": "string" }
              },
              "addendum": {
                "type": "object",
                "additionalProperties": true
              }
            }
          },
          "bbox": {
            "type": "array",
            "description": "Feature bounding box [minLon, minLat, maxLon, maxLat]",
            "items": { "type": "number" },
            "minItems": 4,
            "maxItems": 4
          }
        }
      }
    },
    "bbox": {
      "type": "array",
      "description": "Collection bounding box [minLon, minLat, maxLon, maxLat]",
      "items": { "type": "number" },
      "minItems": 4,
      "maxItems": 4
    }
  }
}