AfriGIS Address Search

The AfriGIS Address Search headless Library is aimed at creating accessible underlying logic and functionality to implement AfriGIS Search UI components without prescribing a specific visual style.

Quick features

Configure Debounce rate

The debounce rate is the time, measured in milliseconds, to wait after initial input before registering any subsequent inputs. The default setting is 350ms.

Configure Minimum characters for suggestions

Specify the minimum number of characters of input required before address suggestions are returned. The default is 3 characters.

Configure Max Results for suggestions

Specify the maximum number of address suggestions to return in the results. The default value is 5, but values of between 1 and 20 are accepted.

Configure Include Types for autocomplete and address search

Specify an array of string for the address types to include in the suggestions for Autocomplete API and Geocode API (address search). Refer to Address types for more details.

Configure Exclude Types for autocomplete

Define which address types to include in the suggestions for Autocomplete API, using an array of strings. Refer to Address types for more details.

Configure Points of Interest in autocomplete

Set includeAutocompletePointsOfInterest to true to include points of interest in autocomplete suggestions. This uses the v3.1 autocomplete endpoint internally and also uses v3.1 for place details lookups. The default is false (v3 behavior).

When the address format is set to delivery, POI autocomplete is automatically disabled to prevent non-deliverable suggestion selections. If you switch back to details, the previously selected POI preference is applied again.

Configure Address Components Format for Selected Addresses

AfriGIS provides detailed address information using the Place Details API by structuring the results by address type. Alternatively, the results can be returned in a structure suitable for deliveries by using the Delivery Address Format API

Running Examples

• Clone the repo
• Run NPM Install
• Run Development Server

npm run serve

Initialisation

const agSearch = new AfriGISAddressSearch({
  ...
});

Initialisation takes an options object as input. An explanation of the properties follows:

export interface IAfriGISAddressSearchOptions {
  // API key for authentication.
  // Required
  apiKey: string;                                    

  // Callback handler for when the Suggestions change
  // Required
  onSuggestionsChange: (suggestions: IAfriGISAddressSearchSuggestion[]) => void;                

  // Callback handler for when the Selected Address payload changes
  // Required
  onSelectedAddressChange: (address: string) => void;     

  // Default is "https://afrigis.services"                                      
  baseUrl?: string;

  // Include points of interest in autocomplete suggestions. When true, autocomplete and details use v3.1. Default is false
  includeAutocompletePointsOfInterest?: boolean;

  // Minimum characters required before suggestions engine kick in. Default is 3 characters                                                                           
  minChars?: number;                                                                            

  // Debounce rate in milliseconds, default is 350ms
  debounceMs?: number;                              

  // Maximum amount of suggestions to return, a value between 1 and 20, default is 5                                            
  maxResults?: number;

  // Array of strings to specify which types to include in suggestions, refer to https://developers.afrigis.co.za/oas3/autocomplete-api/api/v3/autocomplete
  includeTypes?: string[]; // array of strings

  // Array of strings to specify which types to exclude in suggestions, refer to https://developers.afrigis.co.za/oas3/autocomplete-api/api/v3/autocomplete
  excludeTypes?: string[]; // array of strings

  // Specifies which format to return the selected Address Payload in. Default is 'details'
  addressComponentsFormat?: 'details' | 'delivery';

  // JWT token for authentication
  jwtToken?: string;
}

Other methods

clear()

Resets the selected Address and the suggestions

inputChanged(input: string)

Fires off the call to retrieve autocomplete suggestions

search(query: string)

Fires off the call to retrieve address search suggestions (a backup to autocomplete)

selectSuggestion(reference:string)

Fires off the call to retrieve the Address Information for a specific address reference

setApiKey(apiKey: string)

Sets the API key (useful in a multitenant situation)

setAddressComponentsFormat(format: 'details' | 'delivery')

Sets the Address Components Format for selected Addresses

Switching to delivery automatically forces autocomplete to address-only mode, even if points of interest were enabled.

setIncludeAutocompletePointsOfInterest(include: boolean)

Enables or disables points of interest in autocomplete suggestions after instantiation.

setToken(token: string)

Sets the JWT token. Necessary for long-running frontends as the JWT token expires in 60 minutes.

Points Of Interest Usage

Enable points of interest when creating an instance:

const agSearch = new AfriGISAddressSearch({
  apiKey: 'YOUR_API_KEY',
  jwtToken: 'YOUR_JWT_TOKEN',
  includeAutocompletePointsOfInterest: true,
  onSuggestionsChange: (suggestions) => {
    console.log(suggestions);
  },
  onSelectedAddressChange: (address) => {
    console.log(address);
  },
});

Toggle points of interest at runtime:

agSearch.setIncludeAutocompletePointsOfInterest(true);
agSearch.setIncludeAutocompletePointsOfInterest(false);