OpenCage API Client

!Maintained

This repository is an OpenCage Geocoding API client for Node Typescript and JavaScript.

Continuous integration


Security

| Source | Scores |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| FOSSA |  |
| Snyk | !Known Vulnerabilities |

🎓 Tutorial

You can find a comprehensive tutorial for using this module on the OpenCage site.

🔧 Getting started

Sign up for a free-trial API Key.

NodeJS

First install the library with npm or yarn:

``bash
npm i --save opencage-api-client
`

or

`bash
yarn add opencage-api-client
`

or

`bash
pnpm add opencage-api-client
`

Starting in v2, dotenv is no longer bundled as a dependency. While we still recommend using .env files for configuration, you'll need to set up dotenv yourself in your project.

Create a .env file with:

`bash
OPENCAGE_API_KEY=YOUR-OPENCAGE_DATA_API_KEY
`

Here are examples:

1. CommonJS

`javascript
require('dotenv').config(); // or add key as an input parameter of the function geocode

const opencage = require('opencage-api-client');

opencage
.geocode({ q: 'lyon' })
.then((data) => {
console.log(JSON.stringify(data));
})
.catch((error) => {
console.log('error', error.message);
});
`

2. ESM

`javascript
import 'dotenv/config'; // or add key as an input parameter of the function geocode

import opencage from 'opencage-api-client';

opencage
.geocode({ q: 'lyon' })
.then((data) => {
console.log(JSON.stringify(data));
})
.catch((error) => {
console.log('error', error.message);
});
`

3. Typescript

This example does not use dotenv and specify the API key as input parameter

`javascript
import { geocode } from 'opencage-api-client';
import type { GeocodingRequest } from 'opencage-api-client';

async function geocode() {
const input: GeocodingRequest = {
q: '51.952659,7.632473',
// The API Key value from process.env.OPENCAGE_API_KEY is overridden by the one provided below
key: '6d0e711d72d74daeb2b0bfd2a5cdfdba', // https://opencagedata.com/api#testingkeys
no_annotations: 1,
};
const result = await geocode(input);
console.log(JSON.stringify(result,null,2));
}
`

Browser

The browser version is built using UMD notation. Modern browser can use the ESM version, here the example use the legacy JS notation.

The library is available with unkpg _CDN_ : https://unpkg.com/opencage-api-client

1- include the library:

`html


`

`html


`

2- use it

`javascript
opencage
.geocode({ q: 'lyon', key: 'YOUR-API-KEY' })
.then((data) => {
console.log(JSON.stringify(data));
})
.catch((error) => {
console.log('Error caught:', error.message);
});
`

3- others Examples

You can find some examples in the examples folder.

✨ API

$3

input: GeocodingRequest

| Parameter | Type | Optional? | Description |
| --------- | ------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| q | String | mandatory | the query string to be geocoded: a place name, address or coordinates as lat,long |
| key | String | optional | the key can be omitted when using an options.proxyURL or when using a node runtime with a dedicated environment variable OPENCAGE_API_KEY |
| ... | ... | optional | Check the type definition and the API documentation for the other input parameters |

options?: _additional optional options_

| Parameter | Type | Optional? | Description |
| --------- | ----------- | --------- | ----------------------------------------------------------------------------------------------------------- |
| signal | AbortSignal | optional | The AbortSignal allow to cancel the request |
| proxyURL | String | optional | The proxy URL parameter (useful to hide your API key) |

$3

API can return errors like invalid key, too many requests, daily quota exceeded, etc. Those errors are thrown as Javascript Error by the geocode function. The error object contains the same status object as the OpenCage API.

Assuming the catch statement uses error as variable name:

`js
console.log('Error caught:', error.message);
`

will output for a 429:

`bash
Error caught: Too Many Requests
`

and

`js
console.log(JSON.stringify(error, null, 2));
`

will output for a 429:

`json
{
"status": {
"code": 429,
"message": "Too Many Requests"
}
}
`

Check the examples using the Test API key from OpenCage error handling examples

🔨 Build and test

1. Fork or clone this repository
1. cd into the repository folder
1. pnpm install to install all the required dependencies from npm
1. echo "OPENCAGE_API_KEY=YOUR-OPENCAGE_DATA_API_KEY" >.env to allow integration tests with your API key
1. lint and test coverage using pnpm run test:coverage
1. Build : pnpm run build
1. Test with the examples running ./scripts/run-examples.sh`

🛣 Revision History

Check the CHANGELOG file.

🥂 Contributing

Anyone and everyone is welcome to contribute.

🐞 Issues

Find a bug or want to request a new feature? Please let me know by submitting an issue.

🗝 Licensing

Licensed under the MIT License

A copy of the license is available in the repository's LICENSE file.