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.