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
string
Place name to search for.
options.apiKey
string?
Custom MapTiler Cloud API key to use instead of the one in global config.
options.limit
number?
 Maximum number of results to show. Must be between 1 and 10. (Default is 5 for forward and 1 for reverse geocoding)
options.types
( Array<string>)?
Filter of feature types to return. If not specified, features of all types except `poi` and `major_landform` are returned
options.excludeTypes
boolean?
Set to true to use all available feature types except those mentioned in types. (Default value is false if types is specified).
options.language
( language | Array<Language>)?
Prefer results in specific languages. It’s possible to specify multiple values.
options.bbox
Array<number>?
Only search for results in the specified area. Bounding box [w, s, e, n] array (Coordinates in WGS 84).
options.proximity
Array<number>?
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).
options.country
Array<string>?
Limit search to specific country/countries specified as a list of Alpha-2 ISO 3166-1 codes.
options.fuzzyMatch
boolean?
Set to false to disable fuzzy (typo-tolerant) search. (Default value is true).
options.autocomplete
boolean?
Set to true to use autocomplete, false to disable it. (Default value is true).

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
Array<number>
Search location. A [lon, lat] array (Coordinates in WGS 84).
options.apiKey
string?
Custom MapTiler Cloud API key to use instead of the one in global config.
options.limit
number?
Maximum number of results to show. Must be between 1 and 10. (Default is 5 for forward and 1 for reverse geocoding)
options.types Filter of feature types to return. If not specified, features of all types except `poi` and `major_landform` are returned.
options.excludeTypes
boolean?
Set to true to use all available feature types except those mentioned in types. (Default value is false if types is specified).
options.language
( language | Array< 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.

Geocoding by ID

Batch Geocoding

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.