Introduction

AfriGIS SRW Reverse Geocode Stored Query API is part of the AfriGIS SRW API suite. The Reverse Geocode API uses coordinate input (as latitude and longitude) of a geographic feature/(s) to provide the human-readable address. It consists of Smart Reverse Geocode and Basic Reverse Geocode.

Overview

Making use of AfriGIS SRW Reverse Geocode Stored Query API, client applications/solutions can obtain a human-recognisable address, such as province, suburb or street address, for a coordinate point. The longitude and latitude are required parameters for both Smart and Basic geocode. The optional parameters differ between the two.

Smart geocode include optional parameters for the number of results to return (limit) as well as the address tile server level of results (level). The response fields not only include the human readable address but also information on the proximity of the spatial feature to the response coordinates.

Basic geocode has, in addition to the latitude and longitude, the required parameters for schema filtering of results to include only one of the available feature types. Optional parameters are the inclusion of results in a radius of a circle centred on the specific location and the option to limit the number of results to return.

API Authentication

This API makes use of OAuth2 – please refer to OAuth2 authentication

srw-reversegeocode-sq-api

View the API in Swagger UI

The reverse geocoding stored query allows you to look up a single pair of coordinates and returns the geographic feature(s) that exist at that location.

This service currently only supports the following African countries

• South Africa
• Namibia

Base URL: https://afrigis.services/srw-reversegeocode-sq/

Smart Reverse Geocode

GET /api/v3/storedquery/reversegeocode/smart

Matches geographic feature(s) that exists by using a single pair of coordinates

Parameters

Name	In	Type	Required	Description
longitude	query	number(double)	true	The Longitude geographic coordinate that specifies the east–west position of the location.
latitude	query	number(double)	true	The Latitude geographic coordinate that specifies the north–south position of the location.
limit	query	integer(int32)	false	The maximum number of results to return. The value must be between 1 and 15.
level	query	integer(int32)	false	The zoom level corresponding to AfriGIS Tileserver. The value must be between 1 and 20.

API Response Structure

{
  "result": [
    {
      "place_id": "string",
      "seoid": "string",
      "sfid": "string",
      "formatted_address": "string",
      "confidence": 0,
      "location": {
        "lng": 0,
        "lat": 0,
        "distance": 0
      },
      "distance": 0,
      "landparcel_ind": "string"
    }
  ],
  "code": 0,
  "message": "string",
  "source": "string"
}

Example API Response:

{
    "result": [
        {
            "place_id": "2XIAs5De9f_eEXNFubwV-ZXI41F281017",
            "seoid": "2XIAs5De9f_eEXNFubwV-ZXI41F281017",
            "sfid": "5c3659ba-335b-5ebd-e053-0d05000aa120",
            "formatted_address": "446 Rigel Avenue South, Erasmusrand, Pretoria, Gauteng, 0181",
            "confidence": 1,
            "location": {
                "lng": 28.256111,
                "lat": -25.808699,
                "distance": 10.03
            },
            "distance": 0.0,
            "landparcel_ind": "Y"
        }
    ],
    "code": 200,
    "message": "OK",
    "source": "srw.api-storedquery-reversegeocode"
}

API Response Object:

The response to a Reverse Geocoding API request is an object that contains the following properties:

Name	Type	Required	Restrictions	Description
result	string	false	none	an object of returned results for the API request
code	string	false	none	a three digit http response status code
message	string	false	none	a human-readable explanation of the response code
source	string	false	none	a human-readable description of the response source

The result property may have the following properties described below:

Name	Type	Required	Restrictions	Description
place_id	string	false	none	Unique internal identifier denoting a place and or geographic location
seoid	string	false	none	Unique stable textual identifier denoting a place and or geographic location
sfid	string	false	none	Unique spatial feature identifier denoting a geographic feature
formatted_address	string	false	none	The complete formatted address presentation of an address
confidence	number (int)	false	none	The absolute level specifying the relative position to which the address location was captured
location	object	false	none	An object describing the location of the address
location.lat	number (double)	false	none	The latitude coordinate associated with the location
location.lng	number (double)	false	none	The longitude coordinate associated with the location
location.distance	number (int)	false	none	The distance measured in meters from the supplied geographic coordinate to the location geographic coordinate
distance	number (int)	false	none	The distance measured in meters from the supplied geographic coordinate to the location spatial context
landparcel_ind	string	false	none	Spatial topology boolean indicator indicating if supplied geographic coordinate is within a land pacel

Response Codes

Status	Meaning	Description
200	OK	Reverse Geocode results are successfully retrieved
400	Bad Request	Invalid request (bad request; a required parameter is missing; invalid version; invalid format)
404	Not Found	The requested resource was not found
405	Method Not Allowed	Method not allowed (non-GET request)
500	Internal Server Error	Internal system error has occurred

Basic Reverse Geocode

GET /api/v3/storedquery/reversegeocode/basic

Matches targeted geographic feature(s) that exists by using a single pair of coordinates

Parameters

Name	In	Type	Required	Description
longitude	query	number(double)	true	The Longitude geographic coordinate that specifies the east–west position of the location.
latitude	query	number(double)	true	The Latitude geographic coordinate that specifies the north–south position of the location.
schema	query	string	true	Filter results to include only a subset (one) of the available feature types. Available values: adm_adminarea_l1, adm_locality, adm_sublocality, zaf_streetsegment, zaf_streetnode, zaf_landparcel_erven, zaf_landparcel_farm, zaf_landparcel_farmportion, zaf_landparcel_holding, zaf_landparcel_park, zaf_landparcel_street, zaf_nad, zaf_scheme
radius	query	number(double)	false	The radius of the circle centred on the specified location specified in meters. Feature types within this circle radius are considered to be a match.
limit	query	integer(int32)	false	The maximum number of results to return. The value must be between 1 and 15.

API Response Structure

{
  "result": [
    {
      "place_id": "string",
      "seoid": "string",
      "sfid": "string",
      "formatted_address": "string",
      "confidence": 0,
      "location": {
        "lng": 0,
        "lat": 0,
        "distance": 0
      },
      "distance": 0,
      "landparcel_ind": "string"
    }
  ],
  "code": 0,
  "message": "string",
  "source": "string"
}

Example API Response:

{
    "result": [
        {
            "place_id": "2XIAs5De9f_eEXNFubwV-ZXI41F281017",
            "seoid": "2XIAs5De9f_eEXNFubwV-ZXI41F281017",
            "sfid": "5c3659ba-335b-5ebd-e053-0d05000aa120",
            "formatted_address": "446 Rigel Avenue South, Erasmusrand, Pretoria, Gauteng, 0181",
            "confidence": 1,
            "location": {
                "lng": 28.256111,
                "lat": -25.808699,
                "distance": 10.03
            },
            "distance": 0.0,
            "landparcel_ind": "Y"
        }
    ],
    "code": 200,
    "message": "OK",
    "source": "srw.api-storedquery-reversegeocode"
}

API Response Object:

The response to a Reverse Geocoding API request is an object that contains the following properties:

Name	Type	Required	Restrictions	Description
result	string	false	none	an object of returned results for the API request
code	string	false	none	a three digit http response status code
message	string	false	none	a human-readable explanation of the response code
source	string	false	none	a human-readable description of the response source

The result property may have the following properties described below:

Name	Type	Required	Restrictions	Description
place_id	string	false	none	Unique internal identifier denoting a place and or geographic location
seoid	string	false	none	Unique stable textual identifier denoting a place and or geographic location
sfid	string	false	none	Unique spatial feature identifier denoting a geographic feature
formatted_address	string	false	none	The complete formatted address presentation of an address
confidence	number (int)	false	none	The absolute level specifying the relative position to which the address location was captured
location	object	false	none	An object describing the location of the address
location.lat	number (double)	false	none	The latitude coordinate associated with the location
location.lng	number (double)	false	none	The longitude coordinate associated with the location
location.distance	number (int)	false	none	The distance measured in meters from the supplied geographic coordinate to the location geographic coordinate
distance	number (int)	false	none	The distance measured in meters from the supplied geographic coordinate to the location spatial context
landparcel_ind	string	false	none	Spatial topology boolean indicator indicating if supplied geographic coordinate is within a land pacel

Response Codes

Status	Meaning	Description
200	OK	Reverse Geocode results are successfully retrieved
400	Bad Request	Invalid request (bad request; a required parameter is missing; invalid version; invalid format)
404	Not Found	The requested resource was not found
405	Method Not Allowed	Method not allowed (non-GET request)
500	Internal Server Error	Internal system error has occurred

 

For the previous version 2 of this documentation, see this deprecated page.