If you are developing a new library or integration that uses the OpenCage Geocoding API please follow these guidelines:
Before you get started
This may seem obvious, but before you start please take 10-15 minutes to read the API docs.
It's only one page.
- OK, ready? First, check the existing list of SDKs and libraries, and make sure what you are planning on writing doesn't already exist. Perhaps you can extend one of the existing projects rather than restarting from scratch?
- Your library should NOT make a request unless you have a valid API key. Please do not store a key in the library, we recommend setting it via an environment variable. See our guide to protecting API keys.
Ensure that your code respects
the various response codes the API can return.
Don't unintentionally build a denial of service tool. Specifically,
if you see a
403response code, your library should stop rather than just carry on. When there is a non-success response code please display the error message - the value of
message, found in the
statusportion of the response - so your user can better understand why a request failed.
For testing we provide various API keys that always return a specific response.
Please use them in your tests.
Similarly, please make sure you handle the case where the request is
valid, but no results are returned. To create this situation in a test
you can request the query
NOWHERE-INTERESTINGwhich will return a valid response with 0 results.
- Please use a unique user-agent string, so we can see how different libraries are being used and more easily identify the source of any problems. Ideally the user-agent string should include the version number of your library.
Be aware that the API response varies slightly between free trial
accounts and paid subscription accounts. Paid accounts do not have the
ratesection of the response - see docs - because paying customers have no hard limits.
Please realise we are offering a geocoding API for the entire world.
The world is a very diverse place. Design your code to be forgiving,
avoid making assumptions about what will be in the
componentsportion of the results. As an example: don't assume we will always return a postcode, much of the world doesn't use postcodes. Indeed, you can not even assume we will return a country or ISO codes, the requested location could be in the middle of the ocean. Please see our discussion of components in the API docs..
- In your documentation or README, please point your users the best practices for using the OpenCage API, particularly our advice for how to format forward geocoding queries.
In your documentation please show a few common usecases:
- at least one example of both forward and reverse geocoding
- print a result to STDOUT
- what happens when there are no results - it was a valid query, but no results were found
Please ensure that you support
the various optional API parameters
particularly things like
- Please put your source code on GitHub, GitLab, etc to make it easy for others to contribute.
- Please add a license to your code. Which one is up to you, but no license makes it harder for others to contribute.
- In your documentation please list any relevant prerequisites that need to be installed for your code to work. Ideally show the exact commands needed to install those prereqs.
- Please submit your code to the relevant package manager (npm, CPAN, pypi, etc) for that language, and link to this in the documentation.
- Please set up an automated build from a service like Github Actions and add a build status badge on the README
- Finally, don't forget to let us know what you've built so we can add it to the list and feature it on our blog (of course giving you full credit for your work)!
Thanks for writing an SDK, we appreciate it! If you have any questions, please just ask us, we are here to help.