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
   

2. Install address/geocoding profile.

   npx @superfaceai/cli@3 install address/geocoding
   

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

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

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 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