- Notifications
You must be signed in to change notification settings - Fork8
Geocoder is a Typescript library which helps you build geo-aware applications by providing a powerful abstraction layer for geocoding manipulations
License
goparrot/geocoder
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
Geocoder is a Typescript library which helps you build geo-aware applications byproviding a powerful abstraction layer for geocoding manipulations.
- Installation
- Usage
- Providers
- Special Geocoders and Providers
- Versioning
- Contributing
- Unit Tests
- Background
- License
$ npm i @goparrot/geocoder reflect-metadata axiosIn the code snippet below we use Google provider.
import'reflect-metadata';import{Distance,Location,Geocoder,GoogleMapsProvider,Suggestion}from'@goparrot/geocoder';importaxios,{AxiosInstance}from'axios';constaxios:AxiosInstance=axios.create();constprovider:GoogleMapsProvider=newGoogleMapsProvider(axios,'YOUR_API_KEY');constgeocoder:Geocoder=newGeocoder(provider);(async()=>{try{constlocations:Location[]=awaitgeocoder.geocode({address:'1158 E 89th St, Chicago, IL 60619, USA',});console.info({ locations});}catch(err){console.error(err);}try{constlocations:Location[]=awaitgeocoder.reverse({lat:41.7340186,lon:-87.5960762,});console.info({ locations});}catch(err){console.error(err);}try{constsuggestions:Suggestion[]=awaitgeocoder.suggest({address:'1158 E 89th St',});console.info({ suggestions});}catch(err){console.error(err);}try{constlocation:Location=awaitgeocoder.placeDetails({placeId:'SOME_GOOGLE_PLACE_ID',});console.info({ location});}catch(err){console.error(err);}try{constdistance:Distance=awaitgeocoder.distance({from:{lat:40.871994,lon:-74.425937,},to:{lat:40.863008,lon:-74.385286,},mode:TravelModeEnum.DRIVING,});console.info({ distance});}catch(err){console.error(err);}})();
In the code snippet below we use Here provider.
import'reflect-metadata';import{Location,Geocoder,HereProvider,LoggerInterface}from'@goparrot/geocoder';importaxios,{AxiosInstance,AxiosRequestConfig,AxiosResponse}from'axios';// You can use any logger that fits the LoggerInterfaceconstlogger:LoggerInterface=console;// Set timeout for all requestsconstaxios:AxiosInstance=axios.create({timeout:5000,});// You can log all requestsaxios.interceptors.request.use((request:AxiosRequestConfig)=>{logger.debug('api request',request);returnrequest;});// You can log all responsesaxios.interceptors.response.use((response:AxiosResponse):AxiosResponse=>{logger.debug(`api response${response.status}`,response.data);returnresponse;});/** * Caching adapter for axios. Store request results in a configurable store to prevent unneeded network requests. *@link {https://github.com/RasCarlito/axios-cache-adapter} */constprovider:HereProvider=newHereProvider(axios,'YOUR_APP_ID','YOUR_APP_CODE');constgeocoder:Geocoder=newGeocoder(provider);geocoder.setLogger(logger);(async()=>{try{constlocations:Location[]=awaitgeocoder.geocode({// accuracy: AccuracyEnum.HOUSE_NUMBER,address:'1158 E 89th St, Chicago, IL 60619, USA',countryCode:'US',// postalCode: '60619',// state: 'Illinois',// stateCode: 'IL',// city: 'Chicago',// language: 'en', // default// limit: 5, // default// fillMissingQueryProperties: true, // defaultwithRaw:true,// default false});logger.info('locations',{ locations});}catch(err){logger.error(err);}try{constlocations:Location[]=awaitgeocoder.reverse({// accuracy: AccuracyEnum.HOUSE_NUMBER,lat:41.7340186,lon:-87.5960762,countryCode:'US',// language: 'en', // default// limit: 5, // default// withRaw: false, // default});console.info('locations',{ locations});}catch(err){console.error(err);}})();
Legend:
- ✅ - Implemented / ready to use
- 🚫 - Provider doesn't support it
- ⌛ - In progress
- 🆘 - Need help with implementation
- 🔍️ - Need to investigate if supported by provider
| Provider | Geocode | Reverse | Suggest | Place Details | Distance |
|---|---|---|---|---|---|
| Algolia Places | 🆘 | 🆘️ | 🆘 | 🆘 | 🔍 |
| ArcGIS Online | ✅ | ✅ | ✅️ | ✅ | 🔍 |
| Bing Maps | 🆘 | 🆘️ | 🔍️ | 🆘 | 🔍 |
| Geonames | 🆘 | 🆘️ | 🔍️ | 🆘 | 🔍 |
| Google Maps | ✅ | ✅ | ✅ | ✅ | ✅ |
| Here | ✅ | ✅ | ✅ | ✅ | 🔍 |
| LocationIQ | 🆘 | 🆘️ | 🔍️ | 🔍 | 🔍 |
| Mapbox | 🆘 | 🆘️ | 🔍️ | 🔍 | 🔍 |
| MapQuest | ✅ | ✅ | 🚫️ | 🚫 | 🔍 |
| Mapzen | 🆘 | 🆘️ | 🔍️ | 🔍 | 🔍 |
| Nominatim | 🆘 | 🆘️ | 🔍️ | 🔍 | 🔍 |
| OpenCage | 🆘 | 🆘️ | 🔍️ | 🔍 | 🔍 |
| Photon | 🆘 | 🆘️ | 🔍️ | 🔍 | 🔍 |
| PickPoint | 🆘 | 🆘️ | 🔍️ | 🔍 | 🔍 |
| TomTom | 🆘 | 🆘️ | 🔍️ | 🔍 | 🔍 |
| Yandex | 🆘 | 🆘️ | 🔍️ | 🔍 | 🆘️ |
TheChainProvider is a special provider that takes a list of providers anditerates over this list to get information. Note that itstops its iterationwhen a provider returns a result.
import'reflect-metadata';importaxios,{AxiosInstance}from'axios';import{Location,ChainProvider,HereProvider,MapQuestProvider,ProviderAggregator}from'@goparrot/geocoder';constaxios:AxiosInstance=axios.create({timeout:5000,});constchainProvider:ChainProvider=newChainProvider([newMapQuestProvider(axios,'YOUR_API_KEY'),newHereProvider(axios,'YOUR_APP_ID','YOUR_APP_CODE')]);constgeocoder:ProviderAggregator=newProviderAggregator([chainProvider]);(async()=>{try{constlocations:Location[]=awaitgeocoder.geocode({address:'1158 E 89th St, Chicago, IL 60619, USA',});console.info({ locations});}catch(err){console.error(err);}})();
TheProviderAggregator is used to register several providers so that you canmanualy decide which provider to use later on.
import'reflect-metadata';importaxios,{AxiosInstance}from'axios';import{Location,GoogleMapsProvider,HereProvider,ProviderAggregator,MapQuestProvider}from'@goparrot/geocoder';constaxios:AxiosInstance=axios.create({timeout:5000,});constgeocoder:ProviderAggregator=newProviderAggregator([newMapQuestProvider(axios,'YOUR_API_KEY'),newHereProvider(axios,'YOUR_APP_ID','YOUR_APP_CODE'),]);geocoder.registerProvider(newGoogleMapsProvider(axios,'YOUR_API_KEY'));(async()=>{try{constlocations:Location[]=awaitgeocoder.using(GoogleMapsProvider).geocode({address:'1158 E 89th St, Chicago, IL 60619, USA',});console.info({ locations});}catch(err){console.error(err);}})();
TheProviderAggregator's API is fluent, meaning you can write:
constlocations:Location[]=geocoder.registerProvider(newMyCustomProvider(axios)).using(MyCustomProvider).geocode({// ...});
Theusing() method allows you to choose theprovider to use by its class name.When you deal with multiple providers, you may want to choose one of them. Thedefault behavior is to use the first one, but it can be annoying.
Geocoder followsSemantic Versioning.
SeeCONTRIBUTING file.
In order to run the test suite, install the development dependencies:
$ npm iThen, run the following command:
$ npm run coverageInspired bygeocoder-php/geocoder
Geocoder isMIT licensed.
About
Geocoder is a Typescript library which helps you build geo-aware applications by providing a powerful abstraction layer for geocoding manipulations