Introduction

AfriGIS Geocode-API uses text address input of a geographic feature/(s) to provide the coordinates as latitude and longitude for that feature. At this stage the Geocode-API only consists of forward geocoding – text to coordinates and not reverse geocoding – coordinates to text.

 

Overview

Making use of AfriGIS Geocode-API applications can match an address to its correct location by converting an address into geographical coordinates. Applications submit an address or a search string containing partial address information. The result is either a single record exactly matching the input, or a set of records ranked by relevance when the input is ambiguous.

Matches an address to its correct location by converting an unstructured address into geographical coordinates.

API Authentication

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

geocode

View the API in Swagger UI

The Geocode API matches an address to its correct location by converting an unstructured address into geographical coordinates.

Base URL: https://afrigis.services/geocode/

Geocode

GET /api/v3/address

Matches an address to its correct location by converting an unstructured address into geographical coordinates.

Parameters

Name In Type Required Description
query query string true The textual address to be used for geocoding
max_results query integer(int32) false The maximum number of results the geocoder must match the input query with. The value must be greater than 0. Default: 10.
include_types query array[string] false The types of address results to return. If no type is specified, all address types will be returned .

API Response Structure

{
    "number_of_records": 0,
    "result": [
        {
            "place_id": "string",
            "seoid": "string",
            "sfid": "string",
            "formatted_address": "string",
            "confidence": {
                "confidence_id": 0,
                "description": "string"
            },
            "location": {
                "lat": 0,
                "lng": 0
            },
            "types": [
                "string"
            ]
        }
    ],
    "code": 0,
    "message": "100 CONTINUE",
    "source": "string"
}

Example API Response:

{
    "number_of_records": 1,
    "result": [
        {
            "place_id": "63s02h_Rmu3070D61",
            "seoid": "63s02h_Rmu3070D61",
            "sfid": "5c362967-34e8-5ad4-e053-0d05000aa265",
            "formatted_address": "Wierda Crest Estate, Centurion, Gauteng",
            "confidence": {
                "confidence_id": 7,
                "description": "Centre of sublocality boundary"
            },
            "location": {
                "lat": -25.881964,
                "lng": 28.153511
            },
            "types": [
                "sublocality_level_1",
                "sublocality",
                "political"
            ]
        }
    ],
    "code": 200,
    "message": "OK",
    "source": "geocode.api-address"
}

Please note: For readability purposes the above example API response has been reduced to only show one geocoded result.

API Response Object:

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

Name Type Required Restrictions Description
number_of_records integer (int32) false none The total number of results the geocoder matched the input query with.
result string false none an array 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 object false none An object describing the relative position to which the address location was captured. See the list of confidence levels.
confidence.confidence_id number (int) false none The absolute level specifying the relative position.
confidence.description string false none The description of the absolute level specifying the relative position.
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.
types array false none An array of address types describing the type of an address. See the list of address types.

Response Codes

Status Meaning Description
200 OK 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.

Example address types supported

Please see table below with example addresses and responses supported.

Address Type Response
Locality
South Africa country
political
view
Gauteng administrative_area_level_1
political
view
King Cetshwayo District Municipality, KwaZulu-Natal administrative_area_level_2
political
view
City of Tshwane Metropolitan Municipality, Gauteng administrative_area_level_3
political
view
Centurion, Gauteng locality
political
view
Wierda Crest Estate, Centurion, Gauteng sublocality_level_1
sublocality
political
view
Rooihuiskraal Noord Ext 25, Centurion, Gauteng sublocality_level_2
sublocality
colloquial_area
political
view
Street
Cineraria Street, Wierda Crest Estate, Centurion, Gauteng, 0157 route_level_1
route
view
Cineraria Street, Rooihuiskraal Noord Ext 25, Centurion, Gauteng, 0157 route_level_2
route
view
6974 Cineraria Street, Wierda Crest Estate, Centurion, Gauteng, 0157 street_address_level_1
street_address
view
6974 Cineraria Street, Rooihuiskraal Noord Ext 25, Centurion, Gauteng, 0157 street_address_level_2
street_address
view
Building
VILLA MARELLE, Wierda Crest Estate, Centurion, Gauteng, 0157 premise_level_1
premise
view
VILLA MARELLE, Rooihuiskraal Noord Ext 25, Centurion, Gauteng, 0157 premise_level_2
premise
view
Villa Casia, Theresapark, Akasia, Gauteng, 0182 premise_level_3
premise
view
Unit 1 VILLA MARELLE, Wierda Crest Estate, Centurion, Gauteng, 0157 subpremise_level_1
subpremise
view
Unit 1 VILLA MARELLE, Rooihuiskraal Noord Ext 25, Centurion, Gauteng, 0157 subpremise_level_2
subpremise
view
1908 Villa Casia, Theresapark, Akasia, Gauteng, 0182 subpremise_level_3
subpremise
view
Intersection
Cnr Cineraria Street and Blueblossom Street, Wierda Crest Estate, Centurion, Gauteng, 0157 intersection_level_1
intersection
view
Cnr Cineraria Street and Blueblossom Street, Rooihuiskraal Noord Ext 25, Centurion, Gauteng, 0157 intersection_level_2
intersection
view
Site
Erf 4088 Wierda Crest Estate, Centurion, Gauteng, 0157 site_address_erven_level_1
site_address_erven
site_address
view
Erf 4088 Rooihuiskraal Noord Ext 25, Centurion, Gauteng, 0157 site_address_erven_level_2
site_address_erven
site_address
view
Farm 412 Tierhoek, Lindley, Nketoana Local Municipality, Free State site_address_farmportion_level_1
site_address_farmportion
site_address
view
Plot 112 Welgedacht SH, Springs, Gauteng, 1559 site_address_holding_level_1
site_address_holding
site_address
view
Plot 37 Langenhovenpark Ext 34, Bloemfontein, Free State, 9301 site_address_holding_level_2
site_address_holding
site_address
view
Erf 2808 Wierdapark, Centurion, Gauteng, 0157 site_address_park_level_1
site_address_park
site_address
view
Erf 1088 Rooihuiskraal Noord Ext 14, Centurion, Gauteng, 0157 site_address_park_level_2
site_address_park
site_address
view
Erf 4083 Wierda Crest Estate, Centurion, Gauteng, 0157 site_address_street_level_1
site_address_street
site_address
view
Erf 4083 Rooihuiskraal Noord Ext 25, Centurion, Gauteng, 0157 site_address_street_level_2
site_address_street
site_address
view

 

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