jQuery Geocoding Tutorial

Before we dive in to the tutorial ...

This is a tutorial for using the OpenCage Geocoding API in jQuery. Before you can query the API you will need to sign up for an OpenCage API key.

Once you've done that we recommend you spend five minutes on:

Ok, ready?

Using the OpenCage Geocoding API with jQuery

Please note we also have tutorials for javascript and nodejs.

Code example:

  <!-- Load jQuery from a CDN or your server -->
  <script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.3.1/jquery.min.js"></script>
    function geocode(query){
        url: 'https://api.opencagedata.com/geocode/v1/json',
        method: 'GET',
        data: {
          'key': 'YOUR-API-KEY',
          'q': query,
          'no_annotations': 1
          // see other optional params:
          // https://opencagedata.com/api#forward-opt
        dataType: 'json',
        statusCode: {
          200: function(response){  // success
          402: function(){
            console.log('hit free-trial daily limit');
            console.log('become a customer: https://opencagedata.com/pricing');
          // other possible response codes:
          // https://opencagedata.com/api#codes

      // console should now show:
      // 'Goethe-Nationalmuseum, Frauenplan 1, 99423 Weimar, Germany'

Some issues to consider:

Please note that putting your API key in client side javascript means that it is visible to anyone executing that javascript. We recommend you do this only for internal applications.

If you are exposing your code to the world a better technique is to move the geocoding request to server side code that you control and have your javascript query your server. This way you have full overview of what is happening. Here, for example, is a comprehensive tutorial on how to run the query to our servers from Google Cloud.

That being said, one worry that potential clients sometimes raise is that someone will get their key and start using it heavily and they will face a large and unexpected bill. Fear not - that can't happen because of how our pricing works. Customers buy a month in advance, and there is no usage based charging. If we see an explosion of usage we email you and ask if it is expected and the source is known. If yes, and it will be ongoing, we ask you to move to a higher pricing tier in the future, but this never happens as a surprise. If no, we can help you work out what is going on. Please see all the details of how our pricing works.

Start your free trial

2,500 API requests per day.

No credit card required.