simple-multi-geocoder

Features

Geocode forward and reverse.
Autocomplete addresses.
Available both in the browser and node.

Supported providers

Google
Here
Mapbox

Installing

Package manager

Using npm:

$ npm install simple-multi-geocoder

Using yarn:

$ yarn add simple-multi-geocoder

Using pnpm:

$ pnpm add simple-multi-geocoder

Once the package has been installed, import the library using either import or require:

import { geocode, autocomplete } from "simple-multi-geocoder";

Here OAuth 2.0

Besides traditionnal API Key, Here provider supports OAuth 2.0 authentication, see here documentation for more information.

This package provides a helper function to generate the access token.

import { generateHereAccessToken } from "simple-multi-geocoder";
const accessToken = await generateHereAccessToken({
  clientId: "...",
  clientSecret: "...",
});

In that case, you should pass the bearerToken instead of apiKey in the options object.

const response = await geocode.forward("here", {
  credentials: { bearerToken: accessToken },
  query: "Rue du Belvédère 23, 1050 Ixelles, Belgique",
  country: "BE",
  language: "fr",
  limit: 1,
  raw: true,
});

API

Forward geocoding

geocode.forward(provider, options)

import { geocode } from "simple-multi-geocoder";

const API_KEY = "..."; // get it from secure environment
const address = "Rue du Belvédère 23, 1050 Ixelles, Belgique";

const response = await geocode.forward("here", {
  credentials: { apiKey: API_KEY },
  query: address,
  country: "BE",
  language: "fr",
  limit: 1,
});

console.log(response);
/*
{
  formattedAddress: "Rue du Belvédère 23, 1050 Ixelles, Belgique",
  latitude: 50.82679,
  longitude: 4.37359,
  components: {
    streetNumber: "23",
    streetName: "Rue du Belvédère",
    zipcode: "1050",
    city: "Ixelles",
    county: "Bruxelles",
    state: "Bruxelles",
    district: "Flagey - Malibran",
    country: "Belgique",
    countryCode: "BE",
  },
  extra: {
    id: "here:af:streetsection:NEk2q66IKlrCDNB4JhoMOC:CggIBCCc4o62ARABGgIyMw",
    confidence: 1,
  },
}
*/

Parameter	Description
`provider` (required)	Provider (google, here, mapbox) token
`options` (required)	Options object (see below)

options

Parameter	Type	Description
`credentials` (required)	object	Provider access token (see below)
`query` (required)	string	Complete address in string format (e.g. Rue du Belvédère 23, 1050 Ixelles, Belgique)
`language`	string	Language of the returned result (IETF BCP 47 format)
`country`	string	Limit the search to a specific country (ISO_3166-1_alpha-2 format)
`limit`	number	Maximum number of results to be returned (default: 1) (not supported by Google)
`raw`	boolean	Return the raw result
`params`	object	Params object specific to the provider (see below)

credentials

You should provide one of the following fields:

Parameter	Type	Description
`apiKey`	string	Provider api key
`bearerToken`	string	Provider bearer token (only available for Here)

params

You can check the official API documentation from providers to see which options you can pass the geocoder

Google: https://developers.google.com/maps/documentation/geocoding/requests-geocoding?hl=en#geocoding-lookup
Mapbox: https://docs.mapbox.com/api/search/geocoding/#forward-geocoding-with-search-text-input
Here: https://www.here.com/docs/bundle/geocoding-and-search-api-v7-api-reference/page/index.html#/paths/~1geocode/get

Results

We always return an array of object with the following fields

Field	Type	Description
formattedAddress	string	The complete formatted address
latitude	number	The latitude of the result
longitude	number	The longitude of the result
components	object	The address components (see below)
extra	object	An object with additional informations (see below)

components

Field	Type	Description
country	string	The country where is located the result
countryCode	string	The country code of the result (ISO 3166-1 alpha-2 format)
state	string	The state where is located the result
region	string	The region where is located the result
city	string	The city where is located the result
zipCode	string	The postal code of the city
streetName	string	The street name where is located the result
streetNumber	string	The street number where is located the result

extra

Field	Type	Description
id	string	The unique identifier of the result provided by the provider
bbox	object	The bounding box of the result
confidence	number	A number between 0 and 1 indicating how the result location correspond to our query

Reverse geocoding

geocode.reverse(provider, options)

import { geocode } from "simple-multi-geocoder";

const API_KEY = ... // get it from secure environment
const address = "Rue du Belvédère 23, 1050 Ixelles, Belgique"

const coordinates = {
  latitude: 50.82679,
  longitude: 4.37359
}

const response = await geocode.reverse(
  "here",
  { apiKey: API_KEY, coordinates: coordinates, country: "BE", language: "fr", limit: 1 }
)

console.log(response)
/*
{
  formattedAddress: "Rue du Belvédère 23, 1050 Ixelles, Belgique",
  latitude: 50.82679,
  longitude: 4.37359,
  components: {
    streetNumber: "23",
    streetName: "Rue du Belvédère",
    zipcode: "1050",
    city: "Ixelles",
    county: "Bruxelles",
    state: "Bruxelles",
    district: "Flagey - Malibran",
    country: "Belgique",
    countryCode: "BE",
  },
  extra: {
    id: "here:af:streetsection:NEk2q66IKlrCDNB4JhoMOC:CggIBCCc4o62ARABGgIyMw",
    confidence: 1,
  },
}
*/

Parameter	Description
`provider` (required)	Provider (google, here, mapbox) token
`options` (required)	Options object (see below)

options

Parameter	Type	Description
`credentials` (required)	object	Provider access token (see above)
`coordinates` (required)	object	coordinates of the point to reverse geocode
`language`	string	Language of the returned result (IETF BCP 47 format)
`country`	string	Limit the search to a specific country (ISO_3166-1_alpha-2 format)
`limit`	number	Maximum number of results to be returned (default: 1) (not supported by Google)
`raw`	boolean	Return the raw result
`params`	object	Params object specific to the provider (see below)

coordinates

Field	Type	Description
latitude	number	Latitude of the point
longitude	number	Longitude of the point

params

You can check the official API documentation from providers to see which options you can pass the geocoder

Google: https://developers.google.com/maps/documentation/geocoding/requests-reverse-geocoding?hl=en
Mapbox: https://docs.mapbox.com/api/search/geocoding/#reverse-geocoding
Here: https://www.here.com/docs/bundle/geocoding-and-search-api-v7-api-reference/page/index.html#/paths/~1revgeocode/get

Results

We always return an array of object with the following fields

Field	Type	Description
formattedAddress	string	The complete formatted address
latitude	number	The latitude of the result
longitude	number	The longitude of the result
components	object	The address components (see below)
extra	object	An object with additional informations (see below)

components

Field	Type	Description
country	string	The country where is located the result
countryCode	string	The country code of the result (ISO 3166-1 alpha-2 format)
state	string	The state where is located the result
region	string	The region where is located the result
city	string	The city where is located the result
zipCode	string	The postal code of the city
streetName	string	The street name where is located the result
streetNumber	string	The street number where is located the result

extra

Field	Type	Description
id	string	The unique identifier of the result provided by the provider
bbox	object	The bounding box of the result
confidence	number	A number between 0 and 1 indicating how the result location correspond to our query

Autocomplete

autocomplete(provider, options)

import { autocomplete } from "simple-multi-geocoder";

const API_KEY = ... // get it from secure environment
const address = "Rue du Belvédère 23, 1050 Ixelles, Belgique"

const response = await autocomplete(
  "here",
  { apiKey: API_KEY, query: address, country: "BE", language: "fr", limit: 1 }
)

console.log(response)
/*
{
  formattedAddress: "Rue du Belvédère 23",
  components: {
    streetNumber: "23",
    streetName: "Rue du Belvédère",
    zipcode: "1050",
    city: "Ixelles",
    county: "Bruxelles",
    state: "Bruxelles",
    district: "Flagey - Malibran",
    country: "Belgique",
    countryCode: "BE",
  },
  extra: {
    id: "here:af:streetsection:NEk2q66IKlrCDNB4JhoMOC:CggIBCCc4o62ARABGgIyMw"
  },
}
*/

Parameter	Description
`provider` (required)	Provider (google, here, mapbox) token
`options` (required)	Options object (see below)

options

Parameter	Type	Description
`credentials` (required)	object	Provider access token (see above)
`query` (required)	string	Partial address in string format (e.g. Rue du Belvédère 23)
`language`	string	Language of the returned result (IETF BCP 47 format)
`country`	string	Limit the search to a specific country (ISO_3166-1_alpha-2 format)
`limit`	number	Maximum number of results to be returned (default: 1) (not supported by Google)
`raw`	boolean	Return the raw result
`params`	object	Params object specific to the provider (see below)

params

You can check the official API documentation from providers to see which options you can pass the geocoder

Google: https://developers.google.com/maps/documentation/places/web-service/autocomplete?hl=en
Mapbox: https://docs.mapbox.com/api/search/search-box/#get-suggested-results
Here: https://www.here.com/docs/bundle/geocoding-and-search-api-v7-api-reference/page/index.html#/paths/~1autocomplete/get

Results

We always return an array of object with the following fields

Field	Type	Description
formattedAddress	string	The complete formatted address
components (optional)	object	The address components (see below)
extra	object	An object with additional informations (see below)

components

Field	Type	Description
country	string	The country where is located the result
countryCode	string	The country code of the result (ISO 3166-1 alpha-2 format)
state	string	The state where is located the result
region	string	The region where is located the result
city	string	The city where is located the result
zipCode	string	The postal code of the city
streetName	string	The street name where is located the result
streetNumber	string	The street number where is located the result

extra

Field	Type	Description
id	string	The unique identifier of the result provided by the provider

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

README.md

simple-multi-geocoder

Features

Supported providers

Installing

Package manager

Here OAuth 2.0

API

Forward geocoding

geocode.forward(provider, options)

options

credentials

params

Results

components

extra

Reverse geocoding

geocode.reverse(provider, options)

options

coordinates

params

Results

components

extra

Autocomplete

autocomplete(provider, options)

options

params

Results

components

extra

Files

README.md

Latest commit

History

README.md

File metadata and controls

simple-multi-geocoder

Features

Supported providers

Installing

Package manager

Here OAuth 2.0

API

Forward geocoding

geocode.forward(provider, options)

options

credentials

params

Results

components

extra

Reverse geocoding

geocode.reverse(provider, options)

options

coordinates

params

Results

components

extra

Autocomplete

autocomplete(provider, options)

options

params

Results

components

extra