Integrate geocoding the right way

This is the first article in a series covering integrating geocode to Node.js applications in a way that lets you:

• Create an integration that never breaks
• Use different API providers based on location
• Make sure you always get the data you need

There is no single best provider

When integrating geocoding, most developers start by comparing a couple of geocoding API providers, choose the seemingly best one and bake it in their app.

However, there is no single best Geocoding API. Moreover, getting familiar with every considered provider takes time, and hard-wiring just one achieves nothing but vendor lock.

Integrate them all

Instead of looking for a unicorn, integrate the business use-case and access any provider of preference at the runtime. This can be achieved using Superface's open source OneSDK, which serves as a universal interface to many APIs. Here’s how to do it.

Integrate geocoding using Superface OneSDK

The following steps are pretty straightforward, however if this is your first run with Superface or you just want a better understanding of what’s happening under the hood, read the documentation.

1. Install Superface OneSDK package in your project folder.
   

   npm install @superfaceai/one-sdk
   

2. Install address/geocoding profile.
   

   npx @superfaceai/cli install address/geocoding
   

3. Configure desired providers. Nominatim offers their API publicly. No keys required.
   

   # Here.com
   npx @superfaceai/cli configure here -p address/geocoding
   
   # Google Maps
   npx @superfaceai/cli configure google-apis-maps -p address/geocoding
   
   # Azure Maps
   npx @superfaceai/cli configure azure -p address/geocoding
   
   # OpenCage
   npx @superfaceai/cli configure opencage -p address/geocoding
   
   # TomTom
   npx @superfaceai/cli configure opencage -p address/geocoding
   
   # Nominatim
   npx @superfaceai/cli configure nominatim -p address/geocoding
   

   If you need another provider, let me know.

4. Obtain API keys for the desired providers and set them as an environment variable.
   

   # Here.com
   export HERE_API_KEY=your-value-from-here
   
   # Google Maps
   export GOOGLE_APIS_MAPS_API_KEY=your-value-from-google-maps
   
   # Azure Maps
   export AZURE_API_KEY=your-value-from-azure
   
   # OpenCage
   export OPENCAGE_API_KEY=your-value-from-opencage
   
   # TomTom
   export TOMTOM_API_KEY=your-value-from-tomtom
   

   How to get API keys: Here.com | Google Maps | Azure Maps | OpenCage | TomTom

5. Use the following code in your Node.js application and replace the example address with your input:
   

   const { SuperfaceClient } = require('@superfaceai/one-sdk');
   
   async function Geocoding() {
     const sdk = new SuperfaceClient();
   
     // Load the installed profile
     const profile = await sdk.getProfile('address/geocoding');
   
     // Choose the provider
     const provider = await sdk.getProvider('nominatim');
   
     // Use the profile
     const result = await profile
       .getUseCase('Geocode')
       .perform({
         addressCountry: 'United States',
         addressLocality: 'Manhattan',
         postalCode: 'NY 10036',
         streetAddress: 'Times Square',
       },
       { provider }
     );
   
     // Check out the result
     try {
       const data = result.unwrap();
       console.log(data);
     } catch (error) {
       console.error(error);
     }
   }
   
   Geocoding();
   

6. Run the code.

   Calling the Geocoding function should return a similar result:
   

   { latitude: '40.757280550000004', longitude: '-73.98585503545917' }
   

And that’s it. Your basic integration is ready.

Read next

• Use different providers for different locations

Comments

[Ruanna]

Thanks for the TomTom shoutout!

[aaronjwhipple87]

I am trying to integrate this into a Next.js project I am doing and keep running into module not found such as 'fs'... Could you direct me to some workarounds for this pertaining to Next.js?

[Jan Vlnas]

Hey Aaron thanks for trying it out!
We ran into the issue with Next.js bundling. OneSDK needs to read .supr files which are not included in the bundle. We have an open issue for that, so feel free to report your experience there, or just to subscribe: github.com/superfaceai/one-sdk-js/...

We are currently adjusting the SDK to reduce dependency on filesystem, which should also solve this problem.