GeoCoder SDK

The sdk/geocoder library provides robust services for managing and manipulating location-based use cases, focusing on addresses. Utilizing the GeoCoder.Address as a canonical type, users can search for addresses, map and convert addresses into various formats, and interact with a comprehensive list of countries, focusing on those supported by the platform.

Features

• Address Search and Location Lookup: Find addresses and locations with ease.
• Address Mapping and Stringification: Convert addresses into multiple formats for different use cases.
• Country List Management: Access a comprehensive list of countries and check for application support.

Installation

To get started with sdk/geocoder, install the package using your preferred package manager:

npm install @sdk/geocoder

Setup

Vanilla JavaScript/TypeScript

To use sdk/geocoder, set up the services as follows. Note that the included HxDRAddressService requires an environment url.

import { JsonCountryService, HxDRAddressService } from '@sdk/geocoder';
 
const countryService = new JsonCountryService();
const addressService = new HxDRAddressService('https://env-hxdr.com', countryService);

React

npm install @sdk/geocoder @sdk/geocoder-react react react-dom

Wrapping the application in the GeoCoderProvider allows global access to the services using the useGeocoder hook.

import { GeoCoderProvider } from '@sdk/geocoder-react';
 
<GeoCoderProvider addressService={addressService} countryService={countryService}>
  <Application />
</GeoCoderProvider>;

import { useGeocoder } from '@sdk/geocoder-react';
 
export function Application() {
  const { addressService } = useGeoCoder();
  //...
}

Core Functionalities

CountryService

Manage and interact with country data, including checking if a country is supported by the application.

Available implementations:

• JsonCountryService: Reads country data from memory.

Example

import { JsonCountryService, CountryIsoCode } from '@sdk/geocoder';
 
const service = new JsonCountryService();
service.isCustomerCountryOfResidenceSupported('CH' as CountryIsoCode);

AddressService

Enable address search and typeahead functionalities for an enhanced user experience.

Available implementations:

• HxDRAddressService: Uses the HERE Api for address resolution with HxDR as a proxy. The environment url is required.

Example

import { HxDRAddressService, GeoCoder } from '@sdk/geocoder';
 
const service = new HxDRAddressService('https://env-hxdr.com', countryService);
const addresses: GeoCoder.Address[] = await service.autocompleteAddress('Raeffelstrasse 24');

AddressFormatter

Convert address objects into string representations in various formats.

import { AddressFormatter } from '@sdk/geocoder';
 
const result = AddressFormatter.toString(address, 'FULL');
// Example Output: Street 1 2, 12345 City, State, United States
 
const result = AddressFormatter.toString(address, 'LINE_1');
// Example Output: Street 1 2
 
const result = AddressFormatter.toString(address, 'LINE_2');
// Example Output: 12345 City, State, United States