OpenCage API Client

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

Continuous integration

Security

| Source | Scores | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | FOSSA | | | Snyk | |

🎓 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:

npm i --save opencage-api-client

or

yarn add opencage-api-client

or

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:

OPENCAGE_API_KEY=YOUR-OPENCAGE_DATA_API_KEY

Here are examples:

1. CommonJS

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

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

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:

<!-- latest version -->
<script src="https://unpkg.com/opencage-api-client"></script>

<!-- specific version -->
<script src="https://unpkg.com/[email protected]/dist/opencage-api.min.js"></script>

2- use it

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

geocode(input, options?)

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) |

Error handling

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:

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

will output for a 429:

Error caught: Too Many Requests

and

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

will output for a 429:

{
  "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
2. cd into the repository folder
3. pnpm install to install all the required dependencies from npm
4. echo "OPENCAGE_API_KEY=YOUR-OPENCAGE_DATA_API_KEY" >.env to allow integration tests with your API key
5. lint and test coverage using pnpm run test:coverage
6. Build : pnpm run build
7. 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.