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