opencage-api-client
    Preparing search index...

    opencage-api-client

    OpenCage API Client

    Version Downloads GitHub license Maintained

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

    Node.js CI codecov

    Source Scores
    FOSSA FOSSA Status
    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.

    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);
    });
    1. 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);
    });
    1. 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));
    }

    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/opencage-api-client@1.1.0/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

    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)

    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.

    FOSSA Status