Geocoding - API Client JS

The MapTiler API Client JS provides location search capabilities through both forward (searching by location name) and reverse (searching by geographic coordinates) geocoding functionality to locate specific places and addresses.

For full service information and pricing, check out the MapTiler Geocoding for more details.

If you’re looking to implement a user-friendly search box to your map or apps, explore the MapTiler Geocoding Control module, the main component for integrating location search in interactive applications.

Geocoding functions require real-time data from the MapTiler Geocoding API. Storing or redistributing this data isn't allowed (see our Terms & Conditions). You can purchase our geocoding indexes for on-prem use.

Geocoding functions:

The API Client JS geocoding functions encapsulate calls to the MapTiler API geocoding services to facilitate their use from JavaScript or TypeScript applications. Check out other features and benefits of the API Client JS library.

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 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 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.

Batch Geocoding

The MapTiler API Client JS also supports batch geocoding (handling multiple requests in a single API call). This function expects as a parameter an array of multiple queries. Each query can be forward or reverse.

You can also execute fordward batch geocoding using semicolons (;) to separate individual requests when submitting multiple requests at once.

const maptilerclient = await import("@maptiler/client");
maptilerclient.config.apiKey = "YOUR_MAPTILER_API_KEY";

const batchResults = await maptilerclient.geocoding.batch(['berlin', 'paris', 'london']);
const reverseBatchResults = await maptilerclient.geocoding.batch([[13.388,52.517],[61.192,54.006],[25.329,50.426]]);

//Using semicolons ;
const result = await maptilerclient.geocoding.forward('berlin;paris;london');

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.