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

Search

Add location search capabilities to your solutions with Intiendo Location Services.
Search_2

API DOCUMENTATION

1. Introduction

2. intiendols.basic.geocode.address.2

3. intiendols.basic.geocode.details.2

3.1 Address Types

4. intiendols.basic.geocode.datasets

1. Introduction

AfriGIS Search (powered by IntiendoLS) exposes the AfriGIS datasets as an API (Application Programming Interface) making it easy to search for specific data and integrating address search into applications. Advanced search algorithms and alternative spell checking are used to provide the best possible search results.

Geocoding web services are composed of forward geocoding (which is text to latitude and longitude) and reverse geocoding (latitude and longitude to text) that can be used to find corresponding place and/or address information. Please note that the scope of this API is to cover only the forward geocoding service. For reverse geocoding, see the Reverse Geocode API

Forward Geocoding matches an address to its correct location on the map 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.

Searchable AfriGIS datasets include:

  • National Address Database (NAD)
  • Cadastre (CAD), including farms and agricultural holdings
  • Streets
  • Crossing streets
  • Suburbs
  • Towns
  • Sectional schemes
  • Points of interest
  • Postal codes (Box and Street)
See also:

2. intiendols.basic.geocode.address.2

The Intiendo Search is a search engine with a geocode function, returning the coordinates with the results. This includes current and historic address details in search results. Intiendo Search returns a list of possible matches based on the supplied query string.

Parameters

Required Parameters

ils_location– The address that you want to geocode. Additional address elements such as business names and unit, suite or floor numbers should be avoided. You should URL-encode this parameter, as it may contain spaces, punctuation and especially the ampersand character, which is used to separate parameters in the query string.

Optional Parameters

ils_result_count– The total number of results the geocoder must match the input query with. This parameter will restrict results from the geocoder.

ils_result_start – The starting number where the geocoder must start matching the input query with. This parameter will restrict results from the geocoder. The first result starts at 0, not 1.

ils_addresstypes – A list of address types specified as an array [] or as a comma-separated list, to which to limit the results. See 3.1.1 Filtering by Address Types for more information.

ils_groups– One or more groupings specified as an array [] or as a comma-separated list. Specifying the grouping will enforce the geocoder to add the grouping as part of the result array. Grouping options are:

address_component: Add the address_components[] containing the separate address components

geometry: Add the geometry[] containing geocoded and viewport related components

indent – Specify “true” to format the JSON response in a human-friendly form. Default is “false” to format the JSON response in a compact form.

callback– The callback function name for a JSONP request if you wish to force a cross domain request.

 

Sample Request:

In this example the Geocoding API requests a JSON response for an address “Hatfield, Pretoria”

https://saas.afrigis.co.za/rest/2/intiendols.basic.geocode.address.2/AUTH_PARAMS/?ils_location=Hatfield,+Pretoria&ils_result_count=1

For information on how to calculate AUTH_PARAMS, please visit the API Authentication page.

Click to expand Sample Response

 

Search with address type filter

You can search for only certain types of addresses, for example suburbs and road, by using the ils_addresstypes parameter:

https://saas.afrigis.co.za/rest/2/intiendols.basic.geocode.address.2/myapisamples/AUTH_PARAMS/?ils_location=Hatfield&ils_result_count=3&ils_addresstypes=sublocality&ils_addresstypes=route

For information on how to calculate AUTH_PARAMS, please visit the API Authentication page.

In this example, the search results are filtered by the ils_addresstypes parameter and restricted to “sublocality” and “route”. See 3.1.1 Filtering by Address Types for more information.

Enhanced result groups

By using the ils_groups parameter, you can enhance the results array by adding address_component and geometry groups (see the parameter definition above). For multiple groups, repeat the ils_groups parameter, as in the following example, or use one parameter with a comma-separated list:

Sample Request:

https://saas.afrigis.co.za/rest/2/intiendols.basic.geocode.address.2/myapisamples/AUTH_PARAMS/?ils_location=Hatfield,+Pretoria&ils_result_count=1&ils_groups=geometry&ils_groups=address_component&indent=true

For information on how to calculate AUTH_PARAMS, please visit the API Authentication page.

Click to expand Sample Response

 

Response Description

The JSON response contains an array of results, as well as some status information. Each result contains a formatted address, a confidence level and the input identifier (seoid). Optionally, if you ask for more detail with the ils_groups parameter, it also contains the address_components and geometry.

If you use the callback parameter, the entire JSON will be wrapped in a JSONP function name call.

If code = 200, the JSON response will contain four other root elements:

  • result – contains an array of the geocoded address information and geometry information. See Result below.
  • status – contains metadata on the request.
  • number_of_records – indicates the number of results the geocoder matched the input query with. Generally this number can be used for pagination.
  • qtime – indicates the amount of time measured in milliseconds the geocoder took to process the result from the input query.

Generally, only one entry in the result array is returned for an address lookup, though the geocoder may return several results when address queries are ambiguous.

Result

The results returned from the Geocoding API is placed within a result array. The result array will be empty if no results are returned e.g. when the address doesn’t exist.

A result is made up of the following fields (note that the optional address_components and geometry objects are only present if requested with the ils_groups parameter):

  • docid is a document identifier denoting a place and or geographic location. Note: The docid is deprecated in favour of the seoid.
  • seoid is a unique stable textual identifier denoting a place and or geographic location.
  • formatted_address is a string containing the human-readable address of this location. This address is equivalent to the “postal address/street address”. This address is composed of one or more address components. For example, the address “446 Rigel Avenue, Erasmusrand, Pretoria, Gauteng” contains separate address components for “446” (the street number), “Rigel Ave” (the route), “Erasmusrand” (the sublocality), “Pretoria” (the locality) and “Gauteng” (the administrative subdivision). These address components contain additional information as noted below.
  • confidence is an absolute level specifying the relative position to which the address location was captured.
  • The types[] array indicates the type of the returned result. This array contains a set of zero or more address types. See 3.1.2 Address Types table for more information.

Click to expand optional address_components

  • address_components[] is an array containing the separate address components. Each address_component typically contains:
    • type indicates the type of the address component. See 3.1.2 Address Types table and 3.1.3 Additional Address Component Types table for more information.
    • administrative_type indicates the administrative unit delineated for the purpose of administration.
    • long_name is the full text description of the address component.
    • short_name is an abbreviated textual name for the address component.
    The address_components[] may contain more address components than noted within the formatted_address.

Click to expand optional geometry

  • geometry contains the following information:
    • location contains the geocoded latitude, longitude value.
    • bounds contains the minimum boundary rectangle (mbr), specified as two latitude, longitude values defining the southwest and northeast corner of the bounds bounding box.
    • viewport contains the recommended viewport for displaying the returned result, specified as two latitude, longitude values defining the southwest and northeast corner of the viewport bounding box.

The exact format and element positions of an individual response to the Geocoding API is not guaranteed, since an address requested can change over time. The appropriate values should be selected via expressions.

 

3. intiendols.basic.geocode.details.2

The Details web service returns comprehensive information about a particular place such as address information (which includes, for example, Suburb, Town, Coordinates, etc.) The place is identified by the seoid, passed in the ils_reference parameter.

Parameters

Required Parameters

ils_reference – The address information you want to retrieve based on either a known docid or seoid.

  • docid – a document identifier that uniquely identifies an address and/or geographic location. Note: The docid is deprecated in favour of the seoid
  • seoid – a unique stable textual identifier denoting a place and/or geographic location.
Optional Parameters

ils_groups – One or more groupings specified as an array [] or as a comma-separated list. Specifying the grouping will enforce the geocoder to add the grouping as part of the result array. Grouping options are:

address_component: Add the address_components[] containing the separate address components

geometry: Add the geometry[] containing geocoded and viewport related components

indent – Specify “true” to format the JSON response in a human-friendly form. Default is “false” to format the JSON response in a compact form.

callback– The callback function name for a JSONP request if you wish to force a cross domain request.

Sample Request:

https://saas.afrigis.co.za/rest/2/intiendols.basic.geocode.details.2/AUTH_PARAMS/?ils_reference=2XIAs5De9f_eEXNFubwV-ZXI41F281017&ils_groups=address_component&ils_groups=geometry

For information on how to calculate AUTH_PARAMS, please visit the API Authentication page.

Click to expand Sample Response

 

Response Description

The intiendols.basic.geocode.details.2 response is identical to the intiendols.basic.geocode.address.2 response which has been documented above.

 

3.1 Address Types

The types[] array in the result indicates the address type. Examples of address types include a street address, route address, building address, locality address, site address and more. There is also a type attribute in the address_components[], indicating the type of each part of the address, e.g. street number, route etc.

3.1.1 Filtering by Address Types

If you want to limit search results to a particular set of address types, you can apply a filter with the parameter ils_addresstypes. The parameter can be specified as an array [] or as a comma-separated list, and only results that match the filter will be returned. If this parameter is not specified all address types are returned, based on relevance. The parameter supports address type collections which are not mutually exclusive.

Sample usage for multiple address types:

…&ils_addresstypes=sublocality&ils_addresstypes=route…

OR

…&ils_addresstypes=sublocality,route…

Valid address types for the ils_addresstypes parameter are provided in the first table below, excluding the second table.

3.1.2 Address Types table

This table lists all the address types that are applicable for the ils_addresstypes parameter and the types[] response object. It includes a mapping to their common South African terminology.

Generic addresstypeSouth African terminology
administrative_area_level_1Province
administrative_area_level_2District Council
administrative_area_level_3Municipality
localityTowns
sublocalitySuburbs and SG Towns
   sublocality_level_1Suburbs
   sublocality_level_2SG Towns
routeStreet
street_addressNational Address Database (NAD)
intersectionCrossing street
buildingSectional schemes
   building_level_1Sectional schemes - range of units
   building_level_2Sectional schemes - individual units
siteCadastre (CAD) erven, farm portions, holdings
   site_level_1reserved
   site_level_2Farm portions
   site_level_3Holding
   site_level_4Erf
   site_level_5reserved
   site_level_6reserved
postcode_localityPostal code (Box code and/or Street code) [Geocode only, not Autocomplete]
   postcode_locality_level_1Street code [Geocode only, not Autocomplete]
   postcode_locality_level_2Box code [Geocode only, not Autocomplete]
point_of_interestPoint of interest

3.1.3 Additional Address Component Types table

In addition to the Address Types table above, when you request address components with the ils_groups=address_component option, there may be additional address types in the response that are listed below. (You cannot search for these additional address types with the ils_addresstypes parameter.)

Generic addresstypeSouth African terminology
street_numberPrecise street number
postal_code Postal code
unit Unit number or range number of a building address
site_name Site name, usually a registered farm name
site_number Site number
site_portion Site portion

 

4. intiendols.basic.geocode.datasets

The Datasets web service has been deprecated and is no longer available.

 

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

Project Details