Geocoding - API Client JS

MapTiler API Client JS geocoding (either both forward or reverse) functions allow place identification - either by name or coordinates. See the Geocoding page for more details.

Please, use geocoding functions only from client-side (browser) and do not store or redistribute MapTiler Cloud API data. In case of doubt, consult the terms.

Geocoding functions:

If you want to know the longitude and latitude of a specific place, use forward geocoding:

// in an async function, or as a 'thenable':
const result = await maptilerClient.geocoding.forward('paris');

Parameters

query Place name to search for.
options.apiKey Custom MapTiler Cloud API key to use instead of the one in global config.
options.bbox Only search for results in the specified area. Bounding box [w, s, e, n] array (Coordinates in WGS 84).
options.language Prefer results in specific languages. It’s possible to specify multiple values.
options.proximity Prefer results close to a specific location - features closer to the proximity value will be given priority over those further away. A [lon, lat] array (Coordinates in WGS 84).

Response

Returns a geocoding result geoJSON object

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "id": "county.26864092",
      "properties": {
        "osm_id": "r71525",
        "type": "Admin",
        "country_code": "fr"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [
          2.3483913391828537,
          48.85349527412398
        ]
      },
      "bbox": [
        2.2241219133138657,
        48.815575528950006,
        2.4697572737932205,
        48.90215608857431
      ],
      "center": [
        2.3483913391828537,
        48.85349527412398
      ],
      "place_name": " Paris, France",
      "place_type": [
        "county"
      ],
      "relevance": 1,
      "text": "Paris",
      "context": [
        {
          "id": "subregion.27264572",
          "osm_id": "r8649",
          "type": "Admin",
          "text": "Ile-de-France"
        },
        {
          "id": "region.26859518",
          "osm_id": "r1403916",
          "type": "Admin",
          "text": "Metropolitan France"
        },
        {
          "id": "country.27059822",
          "osm_id": "r2202162",
          "type": "Admin",
          "text": "France"
        }
      ],
      "text_en": "Paris",
      "language_en": "en",
      "place_name_en": "Paris, Ile-de-France, Metropolitan France, France",
      "language": "en",
      "text_es": "París",
      "language_es": "es",
      "place_name_es": "París, Isla de Francia, Francia metropolitana, Francia",
      "text_ca": "París",
      "language_ca": "ca",
      "place_name_ca": "París, Illa de França, França metropolitana, França"
    }
  ],
  "query": [
    "paris"
  ],
  "attribution": "<a href=\"https://www.maptiler.com/copyright/\" target=\"_blank\">&copy; MapTiler</a> <a href=\"https://www.openstreetmap.org/copyright\" target=\"_blank\">&copy; OpenStreetMap contributors</a>"
}

More examples

Search for results in the specified area:

// in an async function, or as a 'thenable':
const result = await maptilerClient.geocoding.forward('paris', {bbox: [-4.724121, 42.940339, 8.327637, 51.454007]});

Prefer results close to a specific location:

// in an async function, or as a 'thenable':
const result = await maptilerClient.geocoding.forward('paris', {proximity: [2.362061, 48.850258]});

Prefer results in Spanish and Korean:

const result = await maptilerClient.geocoding.forward('paris', {language: [maptilerClient.geocoding.language.SPANISH, maptilerClient.geocoding.language.KOREAN]})

Read more about forward geocoding on our official API documentation.

If you wan to know the name of a place, given a longitude-latitude? Use reverse geocoding.

// in an async function, or as a 'thenable':
const result = await maptilerClient.geocoding.reverse([6.249638, 46.402056]);

Parameters

position Search location. A [lon, lat] array (Coordinates in WGS 84).
options.language Prefer results in specific languages. It’s possible to specify multiple values.

Response

Returns a geocoding result GeoJSON object

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "id": "street.22453519",
      "properties": {
        "osm_id": "w297618514",
        "type": "Street",
        "country_code": "ch"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [
          6.249479949474335,
          46.402196606148465
        ]
      },
      "bbox": [
        6.249479949474335,
        46.402196606148465,
        6.249479949474335,
        46.402196606148465
      ],
      "center": [
        6.249479949474335,
        46.402196606148465
      ],
      "place_name": "Chemin des Vergers 1, Prangins, Switzerland",
      "place_type": [
        "street"
      ],
      "relevance": 1,
      "text": "Chemin des Vergers",
      "context": [
        {
          "id": "municipality.26841535",
          "osm_id": "r1685107",
          "type": "Admin",
          "text": "Prangins"
        },
        {
          "id": "county.27001566",
          "osm_id": "r365575",
          "type": "Admin",
          "text": "District de Nyon"
        },
        {
          "id": "region.26902625",
          "osm_id": "r1702421",
          "type": "Admin",
          "text": "Vaud"
        },
        {
          "id": "country.27253293",
          "osm_id": "r51701",
          "type": "Admin",
          "text": "Switzerland"
        }
      ],
      "address": "1",
      "text_en": "Chemin des Vergers",
      "place_name_en": "Chemin des Vergers 1, Prangins, District de Nyon, Vaud, Switzerland",
      "text_es": "Chemin des Vergers",
      "place_name_es": "Chemin des Vergers 1, Prangins, District de Nyon, Valdia, Suiza",
      "text_ca": "Chemin des Vergers",
      "place_name_ca": "Chemin des Vergers 1, Prangins, District de Nyon, Vaud, Suïssa"
    }
  ],
  "query": [
    "6.2496380000000045",
    "46.402056"
  ],
  "attribution": "<a href=\"https://www.maptiler.com/copyright/\" target=\"_blank\">&copy; MapTiler</a> <a href=\"https://www.openstreetmap.org/copyright\" target=\"_blank\">&copy; OpenStreetMap contributors</a>"
}

More examples

Prefer results in French:

// in an async function, or as a 'thenable':
const result = await maptilerClient.geocoding.reverse([6.249638, 46.402056], {language: maptilerClient.geocoding.language.FRENCH});

Read more about reverse geocoding on our official API documentation.

Language

For both forward and reverse geocoding, this library provides a list of supported languages as shorthands to ISO language codes. The result will be provided in multiple languages if the language options is an array.

const result = await maptilerClient.geocoding.forward('paris', {language: [maptilerClient.geocoding.language.SPANISH, maptilerClient.geocoding.language.KOREAN]})

The special language AUTO will detect the platform/browser preferred language.