Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
NodeGeocoder
✓ const NodeGeocoder = require('node-geocoder');
✗ import NodeGeocoder from 'node-geocoder';
import { NodeGeocoder } from '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
✓ const options = {
provider: 'google',
apiKey: 'YOUR_API_KEY' // Mandatory for most providers
};
✗ const options = { provider: 'google' };
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.
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();
Debug
Known issues
gotchaMost 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.fixEnsure 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.
affects: >=1.0
gotchaGeocoding 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.fixImplement 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.
affects: >=1.0
gotchaWhile `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.fixStick 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. affects: 4.x
gotchaAPI 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.fixWhen 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).
affects: >=1.0
gotchaThe 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.fixFor 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).
affects: <4.0 (for older Node versions), or any version without global fetch
Errors
Common errors & fixes
Error: Missing API key for provider [providerName]
The geocoding request was made to a provider that requires an API key, but none was provided or it was invalid.
fixObtain 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.
TypeError: geocoder.geocode is not a function
The `NodeGeocoder` function was not called with options to instantiate a geocoder object, or the returned object was not correctly assigned.
fixEnsure you instantiate the geocoder correctly: `const geocoder = NodeGeocoder(options);`. The `NodeGeocoder` export itself is the factory function, not the geocoder instance.
status is REQUEST_DENIED. You must use an API key to authenticate each request to Google Maps Platform APIs.
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.
fixVerify 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.
SyntaxError: await is only valid in async functions and the top level bodies of modules
Using `await` outside of an `async` function or a top-level ESM module context.
fixWrap 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.
Audit
Dependencies
No dependency data recorded yet.