Node Geocoder

4.4.1 verified Thu Apr 23 auth: no javascript

Node Geocoder is a flexible geocoding and reverse geocoding library for Node.js, providing a unified API to various geocoding services. It currently stands at version 4.4.1 and sees a stable release cadence. Key differentiators include its extensive support for over a dozen providers such as Google Maps, MapQuest, OpenStreetMap, HERE, and ArcGIS Online, allowing developers to switch services without major code changes. The library abstracts away provider-specific API quirks, offering consistent input and output formats. It supports both callback and Promise-based usage, making it adaptable to modern asynchronous JavaScript patterns. Developers must supply their own API keys for most commercial providers, as well as handle potential rate limiting and usage quotas.

Common errors

error Error: Missing API key for provider [providerName] ↓

cause The geocoding request was made to a provider that requires an API key, but none was provided or it was invalid.

fix

Obtain an API key from your chosen provider (e.g., Google Cloud Console, HERE Developer Portal) and pass it in the apiKey property of the geocoder options object.

error TypeError: geocoder.geocode is not a function ↓

cause The `NodeGeocoder` function was not called with options to instantiate a geocoder object, or the returned object was not correctly assigned.

fix

Ensure you instantiate the geocoder correctly: const geocoder = NodeGeocoder(options);. The NodeGeocoder export itself is the factory function, not the geocoder instance.

error status is REQUEST_DENIED. You must use an API key to authenticate each request to Google Maps Platform APIs. ↓

cause Specific to Google Maps, this error indicates a missing, invalid, or improperly configured API key for the Google Geocoding API. It can also mean billing is not enabled for the Google Cloud project.

fix

Verify your Google API key is correct, that the 'Geocoding API' is enabled in your Google Cloud project, and that billing is enabled for the project. Check for any IP or referrer restrictions on the API key that might prevent server-side usage.

error SyntaxError: await is only valid in async functions and the top level bodies of modules ↓

cause Using `await` outside of an `async` function or a top-level ESM module context.

fix

Wrap your geocoding calls in an async function and await the results, then call that async function, or ensure your file is configured as an ESM module if using top-level await.

Warnings

gotcha Most geocoding providers, especially commercial ones like Google, HERE, and MapQuest, require an API key to function. Requests without a valid key will likely be denied. ↓

fix Ensure you obtain and configure an `apiKey` in the options object for your chosen provider. For some providers (e.g., Google), you might also need to enable billing on your cloud project.

gotcha Geocoding services typically enforce rate limits or usage quotas. Exceeding these limits can lead to temporary or permanent service denials, often returning `OVER_QUERY_LIMIT` or similar errors. ↓

fix Implement error handling for rate limit responses, introduce delays between requests for batch operations, consider using client-side geocoding where appropriate, or explore provider-specific enterprise plans. Refer to your chosen provider's documentation for specific limits.

gotcha While `node-geocoder` requires Node.js >=18, its official usage examples in v4.4.1's README utilize CommonJS `require()`. Directly using ESM `import` statements might lead to module resolution issues depending on your project configuration and Node.js environment, as it might primarily expose a CJS module. ↓

fix Stick to `const NodeGeocoder = require('node-geocoder');` as shown in the package's documentation. If you explicitly need ESM, investigate if the package's `package.json` includes an `exports` field for ESM compatibility, or consider using a wrapper.

gotcha API keys with HTTP referrer restrictions might fail for server-side usage (e.g., in Node.js applications deployed to cloud functions or servers). Many server-side calls expect IP address restrictions or no restrictions. ↓

fix When using API keys for server-side geocoding, ensure they are configured for IP address restrictions (if applicable for your provider and deployment) or, if necessary, remove referrer restrictions during initial setup and testing. Always follow security best practices for storing API keys (e.g., environment variables).

gotcha The library's `fetch` option allows a custom HTTP client. If not provided, it relies on the global `fetch` API. In Node.js environments older than 18, `fetch` might not be globally available, leading to runtime errors if no custom `fetch` implementation is supplied. ↓

fix For Node.js versions <18, explicitly provide a `fetch` polyfill or an HTTP client like `node-fetch` via the `options.fetch` property. For Node.js >=18, global `fetch` is available, but a custom `fetch` can still be provided for specific needs (e.g., custom headers, proxies).

Install

npm install node-geocoder

yarn add node-geocoder

pnpm add node-geocoder

Imports

NodeGeocoder
wrong
```
import NodeGeocoder from 'node-geocoder';
import { NodeGeocoder } from 'node-geocoder';
```
correct
```
const NodeGeocoder = require('node-geocoder');
```
The official README examples for v4.4.1 explicitly use CommonJS `require`. While Node.js >=18 supports ESM, the package's primary documented import method in this version is CJS.
NodeGeocoder (Instantiation)
```
const geocoder = NodeGeocoder(options);
```
The library exports a factory function (not a class constructor), which is called directly with an options object to create a geocoder instance.
Options
wrong
```
const options = { provider: 'google' };
```
correct
```
const options = {
  provider: 'google',
  apiKey: 'YOUR_API_KEY' // Mandatory for most providers
};
```
Most geocoding providers require an `apiKey` for authentication and often for accessing specific features or higher rate limits. Omitting it will result in errors for many services.

Quickstart

Demonstrates basic geocoding, reverse geocoding, and advanced options using Google and HERE providers. It includes batch geocoding and uses environment variables for API keys.

const NodeGeocoder = require('node-geocoder');
const nodeFetch = require('node-fetch'); // Required for custom fetch example, otherwise global fetch is used in Node 18+

const API_KEY_GOOGLE = process.env.GOOGLE_GEOCODER_API_KEY ?? '';
const API_KEY_HERE = process.env.HERE_GEOCODER_API_KEY ?? '';

const optionsGoogle = {
  provider: 'google',
  apiKey: API_KEY_GOOGLE,
  formatter: null // Optional: 'gpx', 'string', etc.
};

const optionsHere = {
  provider: 'here',
  apiKey: API_KEY_HERE,
  language: 'en' // Optional, specify language for results
};

const geocoderGoogle = NodeGeocoder(optionsGoogle);
const geocoderHere = NodeGeocoder(optionsHere);

async function runGeocoding() {
  try {
    console.log('--- Google Geocoding ---');
    const resGoogle = await geocoderGoogle.geocode('29 champs elysée paris');
    console.log('Geocode (Google):', resGoogle[0].formattedAddress);

    console.log('\n--- Here Reverse Geocoding ---');
    const resHere = await geocoderHere.reverse({ lat: 45.767, lon: 4.833 });
    console.log('Reverse Geocode (HERE):', resHere[0].formattedAddress);

    console.log('\n--- Google Advanced Geocoding ---');
    const resAdvanced = await geocoderGoogle.geocode({
      address: '29 champs elysée',
      country: 'France',
      zipcode: '75008'
    });
    console.log('Advanced Geocode (Google):', resAdvanced[0].formattedAddress);

    console.log('\n--- Batch Geocoding (Google) ---');
    const batchResults = await geocoderGoogle.batchGeocode([
      '13 rue sainte catherine, bordeaux',
      'another address, london'
    ]);
    console.log('Batch Geocode (Google) Result 1:', batchResults[0][0].formattedAddress);
    console.log('Batch Geocode (Google) Result 2:', batchResults[1][0].formattedAddress);

  } catch (error) {
    console.error('Geocoding error:', error);
  }
}

runGeocoding();