{"id":13431111,"url":"https://github.com/nchaulet/node-geocoder","last_synced_at":"2025-05-14T14:07:38.207Z","repository":{"id":10042345,"uuid":"12088195","full_name":"nchaulet/node-geocoder","owner":"nchaulet","description":"nodejs geocoding library ","archived":false,"fork":false,"pushed_at":"2024-11-17T20:45:23.000Z","size":906,"stargazers_count":942,"open_issues_count":51,"forks_count":213,"subscribers_count":22,"default_branch":"main","last_synced_at":"2025-05-11T11:17:44.645Z","etag":null,"topics":["address-geocoding","geocoder","javascript","node-geocoder","nodejs-library"],"latest_commit_sha":null,"homepage":"http://nchaulet.github.io/node-geocoder/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nchaulet.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":["nchaulet"]}},"created_at":"2013-08-13T17:37:48.000Z","updated_at":"2025-04-25T16:51:13.000Z","dependencies_parsed_at":"2023-01-13T15:42:35.203Z","dependency_job_id":"bfa5a06b-df46-44f5-a2ba-012c1bdc0e5d","html_url":"https://github.com/nchaulet/node-geocoder","commit_stats":{"total_commits":586,"total_committers":94,"mean_commits":6.23404255319149,"dds":"0.42662116040955633","last_synced_commit":"03a67e771dd8dd46ff04d7f80365ea247382672f"},"previous_names":[],"tags_count":53,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nchaulet%2Fnode-geocoder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nchaulet%2Fnode-geocoder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nchaulet%2Fnode-geocoder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nchaulet%2Fnode-geocoder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nchaulet","download_url":"https://codeload.github.com/nchaulet/node-geocoder/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254159194,"owners_count":22024558,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["address-geocoding","geocoder","javascript","node-geocoder","nodejs-library"],"created_at":"2024-07-31T02:01:00.598Z","updated_at":"2025-05-14T14:07:38.189Z","avatar_url":"https://github.com/nchaulet.png","language":"JavaScript","readme":"# node-geocoder\n\n[![Test Status](https://github.com/nchaulet/node-geocoder/actions/workflows/test.yml/badge.svg)](https://github.com/nchaulet/node-geocoder/actions/workflows/test.yml)\n[![npm version](https://img.shields.io/npm/v/node-geocoder.svg?style=flat-square)](https://www.npmjs.com/package/node-geocoder)\n\nNode library for geocoding and reverse geocoding. Can be used as a nodejs library\n\n## Installation (nodejs library)\n\n    npm install node-geocoder\n\n## Usage example\n\n```javascript\nconst NodeGeocoder = require('node-geocoder');\n\nconst options = {\n  provider: 'google',\n\n  // Optional depending on the providers\n  fetch: customFetchImplementation,\n  apiKey: 'YOUR_API_KEY', // for Mapquest, OpenCage, APlace, Google Premier\n  formatter: null // 'gpx', 'string', ...\n};\n\nconst geocoder = NodeGeocoder(options);\n\n// Using callback\nconst res = await geocoder.geocode('29 champs elysée paris');\n\n// output :\n[\n  {\n    latitude: 48.8698679,\n    longitude: 2.3072976,\n    country: 'France',\n    countryCode: 'FR',\n    city: 'Paris',\n    zipcode: '75008',\n    streetName: 'Champs-Élysées',\n    streetNumber: '29',\n    administrativeLevels: {\n      level1long: 'Île-de-France',\n      level1short: 'IDF',\n      level2long: 'Paris',\n      level2short: '75'\n    },\n    provider: 'google'\n  }\n];\n```\n\n## Advanced usage (only google, here, mapquest, locationiq, and opencage providers)\n\n```javascript\nconst res = await geocoder.geocode({\n  address: '29 champs elysée',\n  country: 'France',\n  zipcode: '75008'\n});\n\n// OpenCage advanced usage example\nconst res = await geocoder.geocode({\n  address: '29 champs elysée',\n  countryCode: 'fr',\n  minConfidence: 0.5,\n  limit: 5\n});\n\n// Reverse example\n\nconst res = await geocoder.reverse({ lat: 45.767, lon: 4.833 });\n\n// Batch geocode\n\nconst results = await geocoder.batchGeocode([\n  '13 rue sainte catherine',\n  'another address'\n]);\n\n// Set specific http request headers:\nconst nodeFetch = require('node-fetch');\n\nconst geocoder = NodeGeocoder({\n  provider: 'google',\n  fetch: function fetch(url, options) {\n    return nodeFetch(url, {\n      ...options,\n      headers: {\n        'user-agent': 'My application \u003cemail@domain.com\u003e',\n        'X-Specific-Header': 'Specific value'\n      }\n    });\n  }\n});\n```\n\n## Geocoder Providers (in alphabetical order)\n\n- `agol` : ArcGis Online Geocoding service. Supports geocoding and reverse. Requires a client_id \u0026 client_secret\n- `aplace` : APlace.io Geocoding service. Supports geocoding and reverse. Requires an access token ([read about access tokens here](https://aplace.io/en/documentation/general/authentication)) using `options.apiKey`\n  - For `geocode` you can use simple string parameter or an object containing the different parameters (`type`, `address`, `zip`, `city`, `country`, `countryCode` and `countries`). See available values for `type` and `countries` parameters [here](https://aplace.io/en/documentation/rest-api/search)\n  - For `reverse`, you can pass over `{lat, lon}`\n  - For both methods, use `options.language` (either `fr` or `en`) to specify the language of the results\n- `datasciencetoolkit` : DataScienceToolkitGeocoder. Supports IPv4 geocoding and address geocoding. Use `options.host` to specify a local instance\n- `freegeoip` : FreegeoipGeocoder. Supports IP geocoding\n- `geocodio`: Geocodio, Supports address geocoding and reverse geocoding (US only)\n- `google` : GoogleGeocoder. Supports address geocoding and reverse geocoding. Use `options.clientId`and `options.apiKey`(privateKey) for business licence. You can also use `options.language` and `options.region` to specify language and region, respectively.\n- `here` : HereGeocoder. Supports address geocoding and reverse geocoding. You must specify `options.apiKey` with your Here API key. You can also use `options.language`, `options.politicalView` ([read about political views here](https://developer.here.com/rest-apis/documentation/geocoder/topics/political-views.html)), `options.country`, and `options.state`.\n- `locationiq` : LocationIQGeocoder. Supports address geocoding and reverse geocoding just like openstreetmap but does require only a locationiq api key to be set.\n  - For `geocode` you can use simple `q` parameter or an object containing the different parameters defined here: http://locationiq.org/#docs\n  - For `reverse`, you can pass over `{lat, lon}` and additional parameters defined in http://locationiq.org/#docs\n  - No need to specify referer or email addresses, just locationiq api key, note that there are rate limits!\n- `mapbox` : MapBoxGeocoder. Supports address geocoding and reverse geocoding. Needs an apiKey\n- `mapquest` : MapQuestGeocoder. Supports address geocoding and reverse geocoding. Needs an apiKey\n- `nominatimmapquest`: Same geocoder as `openstreetmap`, but queries the MapQuest servers. You need to specify `options.apiKey`\n- `opencage`: OpenCage Geocoder. Aggregates many different open geocoder. Supports address and reverse geocoding with [many optional parameters](https://opencagedata.com/api#forward-opt). You need to specify `options.apiKey` which can be obtained at [OpenCage](https://opencagedata.com).\n- `opendatafrance`: OpendataFranceGeocoder supports forward and reverse geocoding in France; for more information, see [OpendataFrance API documentation](https://adresse.data.gouv.fr/api/)\n- `openmapquest` : Open MapQuestGeocoder (based on OpenStreetMapGeocoder). Supports address geocoding and reverse geocoding. Needs an apiKey\n- `openstreetmap` : OpenStreetMapGeocoder. Supports address geocoding and reverse geocoding. You can use `options.language` and `options.email` to specify a language and a contact email address.\n  - For `geocode`, you can use an object as value, specifying [one or several parameters](http://nominatim.org/release-docs/latest/api/Search/)\n  - For `reverse`, you can use [additional parameters](http://nominatim.org/release-docs/latest/api/Reverse/)\n  - You should specify a specific `user-agent` or `referrer` header field as required by the [OpenStreetMap Usage Policy](https://operations.osmfoundation.org/policies/nominatim/)\n  - Set `options.osmServer` to use custom nominatim server. Example: you can setup local nominatim server by following [these instructions](http://nominatim.org/release-docs/latest/admin/Installation/) and set `options.osmServer: http://localhost:8000` to use local server.\n- `pickpoint`: PickPoint Geocoder. Supports address geocoding and reverse geocoding. You need to specify `options.apiKey` obtained at [PickPoint](https://pickpoint.io).\n  - As parameter for `geocode` function you can use a string representing an address like \"13 rue sainte catherine\" or an object with parameters described in [Forward Geocoding Reference](https://pickpoint.io/api-reference#forward-geocoding).\n  - For `geocode` function you should use an object where `{lat, lon}` are required parameters. Additional parameters like `zoom` are available, see details in [Reverse Geocoding Reference](https://pickpoint.io/api-reference#reverse-geocoding).\n- `smartyStreet`: Smarty street geocoder (US only), you need to specify `options.auth_id` and `options.auth_token`\n- `teleport`: Teleport supports city and urban area forward and reverse geocoding; for more information, see [Teleport API documentation](https://developers.teleport.org/api/)\n- `tomtom`: TomTomGeocoder. Supports address geocoding. You need to specify `options.apiKey` and can use `options.language` to specify a language\n- `virtualearth`: VirtualEarthGeocoder (Bing maps). Supports address geocoding. You need to specify `options.apiKey`\n- `yandex`: Yandex support address geocoding, you can use `options.language` to specify language\n\n## Fetch option\n\nWith the `options.fetch` you can provide your own method to fetch data. This method should be compatible with the [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API).\n\nThis allow you to specify a proxy to use, a custom timeout, specific headers, ...\n\n## Formatter\n\n- `gpx` : format result using GPX format\n- `string` : format result to an String array (you need to specify `options.formatterPattern` key)\n  - `%P` country\n  - `%p` country code\n  - `%n` street number\n  - `%S` street name\n  - `%z` zip code\n  - `%T` State\n  - `%t` state code\n  - `%c` City\n\n## More\n\n### Playground\n\nYou can try node-geocoder here http://node-geocoder.herokuapp.com/\n\n### Command line tools\n\n[`node-geocoder-cli`](https://github.com/nchaulet/node-geocoder-cli) You can use node-geocoder-cli to geocode in shell\n\n### Extending node geocoder\n\nYou can add new geocoders by implementing the two methods `geocode` and `reverse`:\n\n```javascript\nconst geocoder = {\n    geocode: function(value, callback) { ... },\n    reverse: function(query, callback) { var lat = query.lat; var lon = query.lon; ... }\n}\n```\n\nYou can also add formatter implementing the following interface\n\n```javascript\nconst formatter = {\n  format: function(data) {\n    return formattedData;\n  }\n};\n```\n\n### Contributing\n\nYou can improve this project by adding new geocoders.\n\nTo run tests just `npm test`.\n\nTo check code style just run `npm run lint`.\n","funding_links":["https://github.com/sponsors/nchaulet"],"categories":["JavaScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnchaulet%2Fnode-geocoder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnchaulet%2Fnode-geocoder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnchaulet%2Fnode-geocoder/lists"}