Forward Geocode

Forward geocoding is the process of taking an address as a single string and looking up its associated geographic data. For example, we might search for "32 Thames St, Windsor SL4 1PS" to find its associated coordinates, and, in the case of Naurt, building entrance and parking information.

A forward geocode with the V2 endpoint only requires use of the address_string property. You may also use additional_matches to find more than a single address.

Optionally, you may also do a forward geocode with a location. This will limit the text matching to only happen within the specified area. The area is a circle with radius as specified in metres by the distance_filter property, which defaults to 5000m and has a minimum value of 0m and a maximum value of 25000m.

Use Case

This type of search is actually not particularly recommended. This type of search is used in the case where the input address is a single string, for example again "32 Thames St, Windsor SL4 1PS". This is not ideal and you will get more accurate and faster results if you are able to use the structured address.

If you are building some kind of address service for the first time, we strongly advise you to not make the address field a single string but rather a form which allows address elements to be broken down e.g. street number, street name, post code and so on.

However, there are some applications where this isn't possible. For example, online map views typically have just a single string which is used for search.

The optional location parameter can also be used with map-views, for example, during a "search this area" feature the centre of the search view can be used as the location. Alternatively, if you have a rough indication of the final delivery address already that can also be used.

Examples

The example section shows the final JSONs which can be placed into the request queries list. It should be noted that a single request can contain multiple different kinds of queries.

Standard Forward Geocode

JSON
{
  "address_string": "32 Thames St, Windsor SL4 1PS"
}

Forward Geocode with Country

If you know the country, you should always include it. It will greatly improve search speed. Note that if you use the wrong country, then the correct address can not be found!
JSON
{
  "address_string": "32 Thames St, Windsor SL4 1PS",
  "country": "UK"
}

Forward Geocode with Additional Matches

JSON
{
  "address_string": "32 Thames St, Windsor SL4 1PS",
  "additional_matches": true
}

Forward Geocode with Location

JSON
{
  "address_string": "32 Thames St, Windsor SL4 1PS",
  "location": {
    "latitude": 51.484,
    "longitude": -0.607
  }
}

You can also specify the distance filter yourself, for example, to make it larger. Note that in the above example, the distance is 5000m. In the below request, we extend it to 10000m:

JSON
{
  "address_string": "32 Thames St, Windsor SL4 1PS",
  "location": {
    "latitude": 51.484,
    "longitude": -0.607,
    "distance_filter": 10000.0
  }
}

Forward Geocode, Location and Additional Matches

JSON
{
  "address_string": "32 Thames St, Windsor SL4 1PS",
  "location": {
    "latitude": 51.484,
    "longitude": -0.607,
    "distance_filter": 10000.0
  },
  "additional_matches": true
}

Restrictions

A forward geocode request is incompatible with the id and address_structured properties. Requests that contain address_string and id or address_structured will be rejected with a status code 400.

Table of Contents