Prefix search for places. Useful for autocomplete forms.

v1.0.0

Search for places by prefix

You can use this endpoint to obtain place_id of the location you want, to be used in point endpoint. The response also contains detailed information about the location, such as coordinates, timezone and the country the place belongs to.

Unlike the /find_places endpoint, you should only specify the prefix of the place you are looking for. This is particularly useful for autocomplete forms. You can search for cities, mountains, lakes, countries, ZIP codes, etc. The response can contain multiple places, sorted by relevance. You can then identify the one you want by coordinates, country, or the administrative area.

Input

{
  "type": "object",
  "properties": {
    "key": {
      "type": "string",
      "description": "Your unique API key. You can either specify it in this parameter, or set it in `X-API-Key` header."
    },
    "language": {
      "description": "The language of text summaries and place names (variable names are never translated). Available languages are:\n\n   * ``en``: English\n   * ``es``: Spanish\n   * ``fr``: French\n   * ``de``: German\n   * ``pl``: Polish\n   * ``pt``: Portuguese\n   * ``cs``: Czech\n",
      "type": "object"
    },
    "text": {
      "type": "string",
      "description": "Place name or ZIP code"
    }
  },
  "required": [
    "text"
  ],
  "additionalProperties": false
}

Output

{
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "adm_area1": {
        "type": "string",
        "description": "first-level administrative area (a US state, for example)"
      },
      "adm_area2": {
        "type": "string",
        "description": "second-level administrative area (a US county, for example)"
      },
      "country": {
        "type": "string",
        "description": "name of the country"
      },
      "lat": {
        "type": "string",
        "description": "Latitude of the point, always in the format \\<float><N/S>, for example ``23.5S``"
      },
      "lon": {
        "type": "string",
        "description": "Longitude of the point, always in format \\<float><E/W>, for example ``23.5W``"
      },
      "name": {
        "type": "string",
        "description": "name of the place"
      },
      "place_id": {
        "type": "string",
        "description": "unique identifier of the place, which can be used in /point and /map endpoints"
      },
      "timezone": {
        "type": "string",
        "description": "Timezone of the point in tzinfo format."
      },
      "type": {
        "type": "string",
        "description": "The character of the place. May be one of the following values:\n\n* administrative areas (states, counties, districts...): ``administrative_area``\n* country: ``country``\n* a different political entity from a country (for example, a dependent teritory): ``political_entity``\n* villages, towns and cities: ``settlement``\n* air industry locations: ``airbase``, ``airfield``, ``heliport``, ``airport``, ``airport_terminal``\n* places related to water: ``bay``, ``channel``, ``fjord``, ``lake``, ``pond``, ``falls``, ``gulf``,\n    ``harbor``, ``reservoir``, ``sea``, ``dam``, ``cape``, ``island``, ``peninsula``\n* places related to mountain areas: ``hill``, ``mountain``, ``peak``, ``valley``, ``volcano``, ``canyon``\n* other places related to nature: ``park``, ``reserve``, ``resort``, ``desert``\n* places based on postcodes: ``postcode``\n        "
      }
    }
  }
}