{"id":17836,"library":"node-geocoder","title":"Node Geocoder","description":"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.","status":"active","version":"4.4.1","language":"javascript","source_language":"en","source_url":"https://github.com/nchaulet/node-geocoder","tags":["javascript","geocoder","geocoding","geo","google","maps","mapquest","agol","arcgis"],"install":[{"cmd":"npm install node-geocoder","lang":"bash","label":"npm"},{"cmd":"yarn add node-geocoder","lang":"bash","label":"yarn"},{"cmd":"pnpm add node-geocoder","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"import NodeGeocoder from 'node-geocoder';\nimport { NodeGeocoder } from 'node-geocoder';","symbol":"NodeGeocoder","correct":"const NodeGeocoder = require('node-geocoder');"},{"note":"The library exports a factory function (not a class constructor), which is called directly with an options object to create a geocoder instance.","symbol":"NodeGeocoder (Instantiation)","correct":"const geocoder = NodeGeocoder(options);"},{"note":"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.","wrong":"const options = { provider: 'google' };","symbol":"Options","correct":"const options = {\n  provider: 'google',\n  apiKey: 'YOUR_API_KEY' // Mandatory for most providers\n};"}],"quickstart":{"code":"const NodeGeocoder = require('node-geocoder');\nconst nodeFetch = require('node-fetch'); // Required for custom fetch example, otherwise global fetch is used in Node 18+\n\nconst API_KEY_GOOGLE = process.env.GOOGLE_GEOCODER_API_KEY ?? '';\nconst API_KEY_HERE = process.env.HERE_GEOCODER_API_KEY ?? '';\n\nconst optionsGoogle = {\n  provider: 'google',\n  apiKey: API_KEY_GOOGLE,\n  formatter: null // Optional: 'gpx', 'string', etc.\n};\n\nconst optionsHere = {\n  provider: 'here',\n  apiKey: API_KEY_HERE,\n  language: 'en' // Optional, specify language for results\n};\n\nconst geocoderGoogle = NodeGeocoder(optionsGoogle);\nconst geocoderHere = NodeGeocoder(optionsHere);\n\nasync function runGeocoding() {\n  try {\n    console.log('--- Google Geocoding ---');\n    const resGoogle = await geocoderGoogle.geocode('29 champs elysée paris');\n    console.log('Geocode (Google):', resGoogle[0].formattedAddress);\n\n    console.log('\\n--- Here Reverse Geocoding ---');\n    const resHere = await geocoderHere.reverse({ lat: 45.767, lon: 4.833 });\n    console.log('Reverse Geocode (HERE):', resHere[0].formattedAddress);\n\n    console.log('\\n--- Google Advanced Geocoding ---');\n    const resAdvanced = await geocoderGoogle.geocode({\n      address: '29 champs elysée',\n      country: 'France',\n      zipcode: '75008'\n    });\n    console.log('Advanced Geocode (Google):', resAdvanced[0].formattedAddress);\n\n    console.log('\\n--- Batch Geocoding (Google) ---');\n    const batchResults = await geocoderGoogle.batchGeocode([\n      '13 rue sainte catherine, bordeaux',\n      'another address, london'\n    ]);\n    console.log('Batch Geocode (Google) Result 1:', batchResults[0][0].formattedAddress);\n    console.log('Batch Geocode (Google) Result 2:', batchResults[1][0].formattedAddress);\n\n  } catch (error) {\n    console.error('Geocoding error:', error);\n  }\n}\n\nrunGeocoding();","lang":"javascript","description":"Demonstrates basic geocoding, reverse geocoding, and advanced options using Google and HERE providers. It includes batch geocoding and uses environment variables for API keys."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"4.x"},{"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).","message":"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.","severity":"gotcha","affected_versions":">=1.0"},{"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).","message":"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.","severity":"gotcha","affected_versions":"<4.0 (for older Node versions), or any version without global fetch"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"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.","cause":"The geocoding request was made to a provider that requires an API key, but none was provided or it was invalid.","error":"Error: Missing API key for provider [providerName]"},{"fix":"Ensure you instantiate the geocoder correctly: `const geocoder = NodeGeocoder(options);`. The `NodeGeocoder` export itself is the factory function, not the geocoder instance.","cause":"The `NodeGeocoder` function was not called with options to instantiate a geocoder object, or the returned object was not correctly assigned.","error":"TypeError: geocoder.geocode is not a function"},{"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.","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.","error":"status is REQUEST_DENIED. You must use an API key to authenticate each request to Google Maps Platform APIs."},{"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.","cause":"Using `await` outside of an `async` function or a top-level ESM module context.","error":"SyntaxError: await is only valid in async functions and the top level bodies of modules"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}