jQuery Geocoding Tutorial

This is a tutorial for using the OpenCage geocoding API in jQuery. Please note we also have tutorials for javascript and nodejs. You can also find SDKs for ReactJS, TypeScript, GatsbyJS, and various serverless platforms on our SDKs page.

If you are looking for an autosuggest search box functionality, please see our geosearch service.

Topics covered in this tutorial

• General Background
• Basic javascript example
• Issues to consider
• Further reading

Background

jQuery geocoding example:

<script>
  // load jQuery from a CDN or your server
  function geocode(query){
    $.ajax({
      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#optional-params
      },
      dataType: 'json',
      statusCode: {
        200: function(response){  // success
          console.log('formatted: ' + response.results[0].formatted);
          console.log('coords: ', response.results[0].geometry);
        },
        401: function(){
          console.log('invalid API key');
        },
        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
      }
    });
  }

  $(document).ready(function(){
    // reverse geocoding example
    geocode('50.97751,11.32858');
    // console should now show:
    // 'formatted: Goethe-Nationalmuseum, Frauenplan 1, 99423 Weimar, Germany'
    // 'coords:  Object { lat: 50.9775106, lng: 11.3285424 }'
    //
    // forward geocoding example
    // note: no need to URI encode query, jquery's ajax method does it
    geocode('Frauenplan 1, 99423 Weimar, Germany');
    // console should now show:
    // 'formatted: Goethe-Nationalmuseum, Frauenplan 1, 99423 Weimar, Germany'
    // 'coords:  Object { lat: 50.9775106, lng: 11.3285424 }'

  });
</script>

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.

Please see our detailed guide to protecting your API key(s).

As an added measure of safety subscription customers can define a value for the Access-Control-Allow-Origin header in their account dashboard which will limit AJAX requests to a specific domain. You can find the details in the API documentation.

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