Writing an SDK or integration for the OpenCage Geocoding API

If you are developing a new library or integration that uses the OpenCage Geocoding API please follow these guidelines:

1. 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?
2. 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.
3. 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 402 or 403 response 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 status portion 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.
4. 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-INTERESTING which will return a valid response with 0 results.
5. 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.
6. Be aware that the API response varies slightly between free trial accounts and paid subscription accounts. Paid accounts do not have the rate section of the response - see docs - because paying customers have no hard limits.
7. 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 components portion 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..
8. 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.

9. 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
10. Please ensure that you support the various optional API parameters , particularly things like countrycode, abbrv, language, etc.
11. Please put your source code on GitHub, GitLab, etc to make it easy for others to contribute.
12. Please add a license to your code. Which one is up to you, but no license makes it harder for others to contribute.
13. 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.
14. Please submit your code to the relevant package manager (npm, CPAN, pypi, etc) for that language, and link to this in the documentation.
15. Please set up an automated build from a service like Github Actions and add a build status badge on the README
16. 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)!

Final thoughts

Thanks for writing an SDK, we appreciate it! If you have any questions, please just ask us, we are here to help.

Happy geocoding!