Geocode an Address, or Reverse-Geocode Coordinates

{
  "type": "object",
  "anyOf": [
    {
      "required": [
        "q"
      ]
    },
    {
      "required": [
        "lat",
        "lon"
      ]
    }
  ],
  "properties": {
    "q": {
      "type": "string",
      "description": "address (forward geocode)"
    },
    "lat": {
      "type": "string",
      "description": "latitude (reverse geocode)"
    },
    "lon": {
      "type": "string",
      "description": "longitude (reverse geocode)"
    },
    "maxItems": {
      "type": "string",
      "default": "5"
    }
  },
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "count": {
      "type": "number",
      "description": "Number of entries in `items` (typically 1)."
    },
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "lat": {
            "type": "number"
          },
          "lon": {
            "type": "number"
          },
          "type": {
            "type": "string",
            "description": "Typically the literal string 'geocode'."
          },
          "osmId": {
            "type": "number",
            "description": "The underlying OpenStreetMap element id."
          },
          "address": {
            "type": "object",
            "properties": {
              "city": {
                "type": "string"
              },
              "road": {
                "type": "string"
              },
              "state": {
                "type": "string"
              },
              "region": {
                "type": "string",
                "description": "Present only for some locations (e.g. France)."
              },
              "suburb": {
                "type": "string"
              },
              "country": {
                "type": "string"
              },
              "quarter": {
                "type": "string",
                "description": "Present only for some locations (e.g. Paris)."
              },
              "building": {
                "type": "string",
                "description": "Present only when the place is a named building."
              },
              "postcode": {
                "type": "string"
              },
              "country_code": {
                "type": "string",
                "description": "Lowercase two-letter country code, e.g. 'us', 'fr'."
              },
              "city_district": {
                "type": "string"
              },
              "ISO3166-2-lvl4": {
                "type": "string",
                "description": "Subdivision code, e.g. 'US-NY', 'FR-IDF'."
              },
              "ISO3166-2-lvl6": {
                "type": "string",
                "description": "A finer subdivision code; present only for some locations (e.g. Paris)."
              }
            },
            "description": "Structured address breakdown. Which sub-fields are present varies by location -- e.g. `building` appears for the Statue of Liberty, `quarter`/`region`/`ISO3166-2-lvl6` for the Eiffel Tower. Only the most common fields are listed as likely-present; treat every field here as optional.",
            "additionalProperties": true
          },
          "osmType": {
            "type": "string",
            "description": "The underlying OpenStreetMap element type, e.g. 'way'."
          },
          "category": {
            "type": "string",
            "description": "OSM-style place category, e.g. 'building', 'highway'."
          },
          "importance": {
            "type": "number",
            "description": "A relevance/prominence score; seen ranging from ~0.00009 to ~0.60, so its scale is not confirmed to be a simple 0-1 bound."
          },
          "addressType": {
            "type": "string",
            "description": "Typically identical to `category`."
          },
          "boundingBox": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "maxItems": 4,
            "minItems": 4,
            "description": "Four decimal-degree strings, in order [south lat, north lat, west lon, east lon] (inferred from results' own lat/lon values, not vendor-documented) -- each a numeric value encoded AS A STRING, not a number."
          },
          "displayName": {
            "type": "string",
            "description": "Full formatted address/label for the place, e.g. 'Statue of Liberty, Flagpole Plaza, Manhattan, New York County, New York, 10004, United States'."
          }
        },
        "additionalProperties": true
      }
    }
  },
  "description": "The geocode result.",
  "additionalProperties": true
}