simple-multi-geocoder

v2.3.2

Published

6 months ago

Simple package to geocode and autocomplete with multiple providers.

0High
0Medium
0Low

loicmahieu

matiuso

geocoding

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) | | address | StructuredAddress | Structured address object to geocode (see below) | | language | string | Language of the returned result (IETF BCP 47 format) | | countryCode | 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) |

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:

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

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) | | countryCode | 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

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

| 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) | | countryCode | 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

extra

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

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

simple-multi-geocoder

Features

Supported providers

Installing

Package manager

Here OAuth 2.0

API

Forward geocoding

geocode.forward(provider, options)

options

Object StructuredAddress

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

Object `StructuredAddress`