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

Autocomplete

Simplifying map based search while making the user experience more intuitive.
AutoComplete_2

The Autocomplete API is a rest service that returns predictions for addresses and place names based on a input search string. The Autocomplete service can partially match on words: for example “hatfie” could match “Hatfield, Pretoria, Gauteng, 0028” even though only the start of the address matches.

The Autocomplete API is useful for offering type-ahead or autocomplete results in user interfaces to provide on-the-fly predictions as the user types.

You can then call the Geocode Details web service to return more detailed information about a selected specific place.

See also:

API documentation

1. Introduction

2. Get token request

3. Autocomplete request

4. Get Details request

4.1 Address Types

1. Introduction/How to implement AfriGIS Autocomplete

There are three simple steps in the AfriGIS Autocomplete process:

  1. Request an authentication token from AfriGIS, via your server. Pass this to your browser session or other user interface.
  2. As the user types an address, the query and the token is passed directly to AfriGIS’s server, which returns with address predictions. You can display these predictions as the user types.
  3. Select the desired address from the list of predictions, and pass the seoid to your server, which then calls the secured Get Details method to retrieve the details of the address (e.g. Suburb, Town, Coordinates, etc.)

The three step process is explained in more detail below.

 

 

2. Get Token Request

A security token is required to authenticate the Autocomplete request, and this call allows you to obtain one from the AfriGIS server. This token will be valid for 50 Autocomplete requests or 10 minutes, whichever is used up first.

Sample Request:

https://saas.afrigis.co.za/rest/2/saas.getToken/saasClient/[AUTH_PARAMS]/saasTimestamp

Please note that this is a time-based URL, therefore the sample will not be executable.

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

Click to expand Sample Response

Notes

We highly recommend that you don’t make the GetToken call directly from the user’s browser to the AfriGIS server, but rather go through a proxy page on your server, where your key and shared secret can be protected. This secret should never be exposed in the user’s browser from where it can easily be copied.

The Autocomplete call, using this token, then communicates with the AfriGIS server directly, for maximum performance.

The getToken request needs to be generated for each new user page view, as it is mandatory for the request to have a timestamp, called saasTime, that must match the server time to within 120 seconds. It will also need to be regenerated when the 50 Autocomplete requests have been used up, or if more than 10 minutes has passed since it was generated. It is your responsibility to check and regenerate a token in time.

saasTime is the UTC timestamp in seconds since the epoch (1970). On 27/04/2014, 12:00, saasTime would be 1398600000. Remember that if your device time is in SAST (South Africa), first subtract two (2) hours to convert to UTC or GMT. However, this is not essential as the use of saasTime is self-synchronising and any time zone difference will be corrected on a second call. For more information, see the saasTime error handling on the API Authentication page.

Error Responses

If the response does not contain the JSON string token, an error has probably occurred. The JSON string code should be used to determine which error has occurred; do not parse message.

Click to expand possible Error Responses

FAQ/Possible Error Resolutions:

If saasTime is incorrect, or outside of the time window (currently 120 seconds), you will receive an error message:

In this case, parse the X-ServerTime HTTP header, which contains the correct server timestamp, and calculate the difference between your device time and the server time. Use this same difference as an offset from the new device time for the next web service call. In this way, the device and server times will now be synchronised.

If you make the request without saasTime, you will receive an error message:

Please note that saasTime is mandatory for saas.getToken. See https://developers.afrigis.co.za/api-authentication/#timestamp for more details.

 

3. Autocomplete request

The partial address string is passed (in the query parameter) to the autocomplete handler, along with the security token, and a list of suggestions or predictions is returned, along with a seoid for each. You can use the seoid in the subsequent Get Details request to retrieve further details about the selected address.

Once a token has been generated by the saas.getToken request, it can be used up to 50 times, or for up to 10 minutes, whichever is used up first. The response from the Autocomplete web service includes parameters for the Expiry time and CallsLeft count still available for the token. It is your responsibility as the developer to request a new token just before the token expires to ensure no interruption to the user’s search experience.

An optional callback parameter can be used to handle JSONP calls, which will overcome cross domain call issues.

Do not call the similarly named AutocompleteIntiendoLS.ashx or Autocomplete.ashx – these are old, deprecated and unsupported versions of Autocomplete.

Parameters

Required Parameters

  • query – The textual search string to be used for predictions. You should avoid additional address elements such as business names and unit, suite or floor numbers. 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.
  • token – The security token obtained from AfriGIS.

Optional Parameters

  • ils_result_count – The total number of predictions the Autocomplete service must match the search string with. Default = 5. Maximum = 20.
  • ils_addresstypes – A list of address types specified as an array [] or as a comma-separated list, to which to limit the results. See 4.1.1 Filtering by Address Types for more information.
  • 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 requests

Basic Autocomplete sample request:

https://saas.afrigis.co.za/intiendols/autocomplete/?query=Hatfield&token=cd131f1d-7ebf-443f-b101-c5e5500274ab

Please note this is a time based URL therefore it is not executable.

Click to expand Sample Response

You should check that code = 200 and then iterate through the result array, displaying each description string. The seoid can be used later to get the details of the selected prediction.

The response may also contain zero results, as in this example:

Click to expand Empty Response

Autocomplete with address type filter sample request:

https://saas.afrigis.co.za/intiendols/autocomplete/?query=Hatfield&token=cd131f1d-7ebf-443f-b101-c5e5500274ab&ils_addresstypes=sublocality&ils_addresstypes=route

Please note this is a time based URL therefore it is not executable.

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

Click to expand Sample Response

Response Description

If code = 200, the result array will contain zero or more predictions with the following fields:

  • description – a string containing a human-readable name
  • seoid – a unique stable textual identifier denoting a place and or geographic location
  • docid – a document identifier denoting a place and or geographic location. Note: The docid is deprecated in favour of the seoid.

In addition, the response will contain:

  • token – a copy of the token that was submitted
  • callsLeft – an integer containing the number of calls left for this token, before it becomes invalid
  • expires – an ISO 8601 timestamp in SAST (GMT+2) when this token will expire

It is your responsibility as the developer to use callsLeft and expires to determine when to request a new token to ensure no interruption to the user’s search experience.

 

FAQ/Possible Error Resolutions:

If you get:

The token has probably expired and you will need to obtain a new one with another saas.getToken call.

If you get:

The Autocomplete web service is temporarily unavailable. A fall back would be to perform a normal address search when the user presses Enter.

 

4. Get Details request

Once the user selects the required address from the list of predictions, you should call the intiendols.basic.geocode.details.2 method via your server, by passing the selected seoid in the ils_reference parameter. This will retrieve the address’s details (which include, for example, Suburb, Town, Coordinates, etc.) For more information on the intiendols.basic.geocode.details.2 request, see: AfriGIS Search API – Details

Parameters

Required parameters:

  • ils_reference – The address information you want to retrieve, based on either a known docid or seoid.
    • docid – a document identifier denoting a place 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 JSON response contains the result (in an array of size 1), as well as some status information. The 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 Get Details may return several results when address queries are ambiguous.

Result

The result returned from Get Details 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.

The result is made up of the following fields (note that the optional address_components and geometry 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 4.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 4.1.2 Address Types table and 4.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.

 

4.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.

4.1.1 Filtering by Address Types

If you want to limit Autocomplete predictions 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.

4.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

4.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

 

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

Project Details