simple-multi-geocoder v2.3.1

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,
  },
}
*/

options

Object StructuredAddress

Only available for Here provider for now, you can pass an object with the following fields:

import { StructuredAddress } from "simple-multi-geocoder";
const address: StructuredAddress = {
  street: "Rue du chemin",
  number: "123",
  zip: "1234",
  city: "City",
  countryCode: "Country Code (in ISO 3166-1 alpha-2 format)",
};

credentials

You should provide one of the following fields:

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

components

extra

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,
  },
}
*/

options

coordinates

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

components

extra

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"
  },
}
*/

options

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

components

extra