Permalink
Switch branches/tags
Nothing to show
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
35 lines (18 sloc) 2.56 KB

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

  1. This may seem obvious, but before you start please take 10-15 minutes and read the API docs. It's only one page.

  2. OK, ready? First, check the existing list of 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?

  3. Ensure that your code respects the various response codes. Don't unintentionally build a denial of service tool. Specifically, if you see 402 or 403 response codes, you library should stop rather than just carry on.

  4. 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.

  5. Be aware that the API response varies slightly between free trial accounts and paid customer accounts. Paid accounts do not have the rate section of the response (see docs) because paying customers have no hard limits.

  6. 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.

  7. In your documentation please show a few common usecases:

  • at least one example of both forward and reverse geocoding
  • print a result to STDOUT
  1. Please add a license to your code. Which one is up to you, but no license makes it harder for others to contribute.

  2. Please put your source code on Github, gitlab, etc to make it easy for others to contribute.

  3. In your documentation please list any relevant prerequisites that need to be installed for your code to work.

  4. Please submit your code to the relevant package manager (npm, CPAN, etc) for that language, and link to this in the documentation.

  5. Please set up an automated build from a service like TravisCI and add a build status badge on the README

  6. 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!

If you have any questions, please just ask, we are here to help.

Thank you, and happy geocoding!