{"id":19580965,"url":"https://github.com/tsamaya/opencage-api-client","last_synced_at":"2025-06-23T18:05:27.618Z","repository":{"id":29629176,"uuid":"122289902","full_name":"tsamaya/opencage-api-client","owner":"tsamaya","description":"OpenCage Data geocoder API client","archived":false,"fork":false,"pushed_at":"2025-06-21T07:09:31.000Z","size":5260,"stargazers_count":19,"open_issues_count":6,"forks_count":12,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-06-21T08:19:41.808Z","etag":null,"topics":["geocoder","javascript","nodejs","opencage","opencage-geocoder"],"latest_commit_sha":null,"homepage":"https://tsamaya.github.io/opencage-api-client/","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/tsamaya.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.md","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":"tsamaya"}},"created_at":"2018-02-21T03:56:50.000Z","updated_at":"2025-06-21T07:09:08.000Z","dependencies_parsed_at":"2023-01-14T15:20:44.088Z","dependency_job_id":"79bd9c26-5401-4c34-9e83-ae8f5d7c5d74","html_url":"https://github.com/tsamaya/opencage-api-client","commit_stats":{"total_commits":226,"total_committers":8,"mean_commits":28.25,"dds":0.2654867256637168,"last_synced_commit":"ad3660162b31bcb26a3c08a942b323cf77198df5"},"previous_names":[],"tags_count":27,"template":false,"template_full_name":null,"purl":"pkg:github/tsamaya/opencage-api-client","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tsamaya%2Fopencage-api-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tsamaya%2Fopencage-api-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tsamaya%2Fopencage-api-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tsamaya%2Fopencage-api-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tsamaya","download_url":"https://codeload.github.com/tsamaya/opencage-api-client/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tsamaya%2Fopencage-api-client/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261089419,"owners_count":23107872,"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":["geocoder","javascript","nodejs","opencage","opencage-geocoder"],"created_at":"2024-11-11T07:31:28.658Z","updated_at":"2025-06-23T18:05:27.556Z","avatar_url":"https://github.com/tsamaya.png","language":"JavaScript","funding_links":["https://github.com/sponsors/tsamaya"],"categories":[],"sub_categories":[],"readme":"# opencage-api-client\n\n[![Version](https://img.shields.io/npm/v/opencage-api-client.svg)](https://www.npmjs.com/package/opencage-api-client)\n![Downloads](https://img.shields.io/npm/dw/opencage-api-client)\n[![GitHub license](https://img.shields.io/github/license/tsamaya/opencage-api-client)](https://github.com/tsamaya/opencage-api-client/blob/master/LICENSE.md)\n![Maintained](https://img.shields.io/maintenance/yes/2025.svg)\n\nThis repository is an [OpenCage Geocoding API](https://opencagedata.com/api) client for JavaScript and node.\n\n### Continuous integration\n\n[![CircleCI (all branches)](https://img.shields.io/circleci/project/github/tsamaya/opencage-api-client.svg)](https://circleci.com/gh/tsamaya/opencage-api-client)\n[![codecov](https://codecov.io/gh/tsamaya/opencage-api-client/branch/master/graph/badge.svg)](https://codecov.io/gh/tsamaya/opencage-api-client)\n[![Maintainability](https://api.codeclimate.com/v1/badges/8f0f9ba00ade907ef576/maintainability)](https://codeclimate.com/github/tsamaya/opencage-api-client/maintainability)\n[![Reviewed by Hound](https://img.shields.io/badge/Reviewed_by-Hound-8E64B0.svg)](https://houndci.com)\n\n### Security\n\n| Source                      | Scores                                                                                                                                                                                                                   |\n| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| [FOSSA](https://fossa.com/) | [![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Ftsamaya%2Fopencage-api-client.svg?type=shield)](https://app.fossa.com/projects/git%2Bgithub.com%2Ftsamaya%2Fopencage-api-client?ref=badge_shield) |\n| [Snyk](https://snyk.io/)    | ![Known Vulnerabilities](https://snyk.io/test/github/tsamaya/opencage-api-client/badge.svg)                                                                                                                              |\n\n## Tutorial\n\nYou can find a comprehensive tutorial for using this module [on the OpenCage site](https://opencagedata.com/tutorials/geocode-in-nodejs).\n\n## 🔧 Getting started\n\nSignup for a [free-trial API Key](https://opencagedata.com/users/sign_up).\n\n### node\n\nThe library uses [dotenv](https://www.npmjs.com/package/dotenv) on node runtime to configure OpenCage Geocoding API key. But using `key` as an input parameter is always a possiblity.\n\nFirst install the library with `npm` or `yarn`:\n\n```\n$ npm i --save opencage-api-client\n```\n\nor\n\n```\n$ yarn add opencage-api-client\n```\n\nor\n\n```\n$ pnpm add opencage-api-client\n```\n\nCreate a `.env` file with:\n\n```\nOPENCAGE_API_KEY=YOUR-OPENCAGE_DATA_API_KEY\n```\n\nHere is an example:\n\n```javascript\nconst opencage = require('opencage-api-client');\n\nopencage\n  .geocode({ q: 'lyon' })\n  .then((data) =\u003e {\n    console.log(JSON.stringify(data));\n  })\n  .catch((error) =\u003e {\n    console.log('error', error.message);\n  });\n```\n\n### browser\n\nThe browser version is built over the node one, obviously without the dotenv feature.\n\nThe library is available with `unkpg` _CDN_ : https://unpkg.com/opencage-api-client\n\n1- include the library:\n\n```html\n\u003c!-- latest version --\u003e\n\u003cscript src=\"https://unpkg.com/opencage-api-client\"\u003e\u003c/script\u003e\n```\n\n```html\n\u003c!-- specific version --\u003e\n\u003cscript src=\"https://unpkg.com/opencage-api-client@0.10.0/dist/opencage-api.min.js\"\u003e\u003c/script\u003e\n```\n\n2- use it\n\n```javascript\nopencage\n  .geocode({ q: 'lyon', key: 'YOUR-API-KEY' })\n  .then((data) =\u003e {\n    console.log(JSON.stringify(data));\n  })\n  .catch((error) =\u003e {\n    console.log('Error caught:', error.message);\n  });\n```\n\n3- others Examples\n\nFound some examples in the [examples](./examples/) folder.\n\n## ✨ API\n\n### geocode\n\n| Parameter | Type   | Optional? | Description                                                                                               |\n| --------- | ------ | --------- | --------------------------------------------------------------------------------------------------------- |\n| q         | String | mandatory | the query string to be geocoded: a placename, address or coordinates as lat,long                          |\n| key       | String | optional  | the `key` can be omitted when using a `proxyURL` or when using node with a dedicated environment variable |\n| proxyURL  | String | optional  | The proxy URL parameter (useful to hide your API key)                                                     |\n\n### Error handling\n\nAPI can return errors like invalid key, to many requests, daily quota exceeded, etc. Thoses errors are thrown as Javascript [Error](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) by the `geocode` function. The error object contains the same status object as the [OpenCage API](https://opencagedata.com/api#response).\n\nAssuming the catch statment uses `error` as variable name:\n\n```js\nconsole.log('Error caught:', error.message);\n```\n\nwill output for a 429:\n\n```bash\nError caught: Too Many Requests\n```\n\nand\n\n```js\nconsole.log(JSON.stringify(error, null, 2));\n```\n\nwill output for a 429:\n\n```json\n{\n  \"status\": {\n    \"code\": 429,\n    \"message\": \"Too Many Requests\"\n  }\n}\n```\n\nCheck the examples using the Test API key from OpenCage [error handling examples](./examples/apitestkeys.js)\n\n## 🔨 Build and test\n\n1.  Fork or clone this repository\n1.  `$ cd` into the `repository` folder\n1.  `$ npm install` to install all the required dependencies from [npm](https://www.npmjs.com/)\n1.  lint and test coverage using `$ npm test`\n1.  Build : `$ npm run build`\n\n## 🛣 Revision History\n\nCheck the [CHANGELOG](CHANGELOG.md) file.\n\n## 🥂 Contributing\n\nAnyone and everyone is welcome to contribute.\n\n## 🐞 Issues\n\nFind a bug or want to request a new feature? Please let me know by submitting an issue.\n\n## 🗝 Licensing\n\nLicensed under the MIT License\n\nA copy of the license is available in the repository's [LICENSE](LICENSE.md) file.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftsamaya%2Fopencage-api-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftsamaya%2Fopencage-api-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftsamaya%2Fopencage-api-client/lists"}