PAGE CONTENTS
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.