Skip to content

Simple package to geocode and autocomplete with multiple providers.

License

Notifications You must be signed in to change notification settings

Mathieu-R/simple-multi-geocoder

Repository files navigation

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

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

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

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

About

Simple package to geocode and autocomplete with multiple providers.

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published