Published on

Integrate geocoding the right way

  • Vratislav Kopp
    Vratislav Kopp
    Product Manager
    Social media profiles

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.

    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.

    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: | 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();
      } catch (error) {
  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.

Curious about using a single API client for hundreds of APIs?
Get started for free!

Try Superface

API Change Newsletter

Unlike many other APIs, we only publish changes that won’t break your app. However, they might break your world view of APIs!

Superface s.r.o. needs the contact information you provide to us to send you a monthly newsletter. You may unsubscribe from these communications at any time. For information on how to unsubscribe, as well as our privacy practices and commitment to protecting your privacy, please review our Privacy Policy.

© 2023 Superface