+27 87 310 6400 | products@afrigis.co.za

Reverse Geocoding

Query with coordinates for addresses, closest crossing streets or determine a suburb for a point.

Reverse Geocoding Wizard

The AfriGIS Reverse Geocoding API takes a coordinate (latitude and longitude) and finds the closest address, street or crossing street nearest to the point. It can also determine to what suburb or town the point belongs to.

Key features:

  • The Smart Reverse Geocode algorithm is designed to find the best possible match in a hierarchical way
  • Control the dataset to which you want to reverse geocode
  • Specify the radius to be searched and maximum number of results to return
  • Straight line distances to the match is returned
  • Extremely fast

See also:


1. Overview

2. Smart Reverse Geocode

3. reverseGeocode.reverseGeocode

1. Overview

The API consists of a single method with different parameters. Basic format:


Visit Authentication page to see how to calculate [AUTHENTICATION_PARAMETERS]

  • AUTHENTICATION_PARAMETERS – Required authentication parameters
  • METHOD_PARAMETERS – The API parameters. See API description below.

Sample Request

The following example will reverse geocode (using the Smart Reverse Geocoding method) the given coordinate to a street address:


Sample Response:

For a detailed explanation of the request parameters and the response object, please see the following sections.

2. Smart Reverse Geocode (SRG method)

The SRG method is designed to fullfil the majority of reverse geocode needs. It tries to find the best possible match, depending where the coordinate is.

Optional Parameter (level)

By specifying the optional level parameter, you can assign the SRG a to seed level where to start its reverse geocoding. This is handy when you know the coordinate is inaccurate and a low level result like an address or street does not make sense.

Example: Instruct the SRG method to only start reverse geocode at SUBURB level:

Sample Request

Visit Authentication page to see how to calculate [AUTHENTICATION_PARAMETERS]

Sample Response

3. reverseGeocode.reverseGeocode

The reverseGeocode.reverseGeocode method is the only method in the Reverse Geocoding API with different parameters.

Request Parameters

latitude – Latitude part of the coordinate, mandatory in the call (Type: Double). Example: -34.03656
longitude – Longitude part of the coordinate, mandatory in the call (Type: Double). Example: 23.0529
numResults – The maximum number of results to return per call. Maximum number 10. Count more than 10 will be ignored. This parameter is optional, with the default as 1 (Type: Integer). Example: 5
layer – The layer to reverse geocode on. When the layer is defined (optional), the level parameter is ignored (Type: String). Example: AG_STREETS.  See the table below.
radius – When layer is not defined, radius is ignored. Unit: kilometer (Type: Double). Maximum range applies. Example: 0.5
level – Level 0 – 19 corresponding to AfriGIS’ Tile levels (Type: Integer). When level is (optionally) defined, and either layer or radius then that parameter will be ignored and an intelligent match is preformed. Example: 14
callback – This parameter is used when client provides a method to request data from AfriGIS SAAS server, which is in a different domain, something prohibited by typical web browsers because of the same origin policy
Please note: When both layer and radius is defined this search takes precedence over level search

Options for layer parameter


Response definition (Parent)

qTime – Number of milliseconds the request took to execute on the server (Integer). Example: 59
count– Number of results returned for position (Integer). Example: 2
result – Array of child objects or records that contains the results (object array). See example below
responseCode – Integer result code. 0 = success, error codes (see below)
responseMessage – Descriptive message for the response code (String). Example: Invalid attribute

Result definition (Child)

latitude – (Double) – Latitude part of the coordinate. Example -34.03656
longitude – (Double) – Longitude part of the coordinate. Example 23.05269
docID – (String) – Unique ID for the record. Example AG_NAD|9~357~10479~2944356
description – (String) – The records description. Example 5 CHURCH STREET, KNYSNA CENTRAL, KNYSNA, WESTERN CAPE
datasetID – (Integer) – Unique ID of the record in the dataset. Example 2944356
distance – (Double) – Distance from the supplied coordinate in kilometer (Great circle distance) – Example 0.2358

4. Level, Layer & Radius Examples

Sample Request:


Visit Authentication page to see how to calculate [AUTHENTICATION_PARAMETERS]

Sample Response:

5. Layer & Radius Example

Sample Request:

Visit Authentication page to see how to calculate [AUTHENTICATION_PARAMETERS]

Sample Response:

6. Layer Example

Sample Request:

Visit Authentication page to see how to calculate [AUTHENTICATION_PARAMETERS]

Sample Response:

7. Radius Example

Sample Request:

Visit Authentication page to see how to calculate [AUTHENTICATION_PARAMETERS]

Sample Response:

Project Details