AfriGIS VueJs Address Search

The AfriGIS VueJs Address Search composable 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 Payload 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 inputText = ref('');
const apiKey = ref('YOUR_API_KEY');

const {
  clear,
  isSelected,
  suggestions,
  search,
  selectedAddress,
  selectSuggestion,
  setAddressComponentsFormat,
  setApiKey,
  setExcludeTypes,
  setIncludeTypes,
  setMaxResults,
  setJwtToken,
} = useAfrigisAddressSearch(
  inputText,
  {
    apiKey: apiKey.value,
    // Further options are optional
  },
);

Initialisation takes a ref for input text and an options object as input.

An explanation of the properties follows:

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

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

  // 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;
}

Composable Instance computed Properties

isSelected

Indicator used to show if a suggestion has been selected. Is set to true before the selected address payload is retrieved.

suggestions

Array, with a list of suggestions for an input, elements implement IAfriGISAddressSearchSuggestion.

selectedAddress

Object, containing the payload of a selected Address. Format depends on the addressComponentsFormat that was set.

Composable Instance functions

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 multi-tenant situation)

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

Sets the Address Information Format for selected Addresses

setToken(token: string)

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

setIncludeTypes(values: string[])

Sets the Include Types to limit suggestions to specific address types.

setExcludeTypes(values: string[])

Sets the Exclude Types to exclude specific address types from suggestions.