SDK
Packages
Geocoder

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 install this package, you need to have access to the private @sdk npm scope.

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