The Typedown search type is optimized for users to start searching with the most general address element and, once that has been found, move on to more specific parts of the address. Typedown is a useful search option when a user is certain of the address information.
Typedown generally involves two, three or four stages. Prompt sets are used to guide the user as to what information should be entered at each stage. The Typedown search type usually returns a list of suggestions after three or four characters, from which the user can select a place name from the first stage. Ideally, the user will always enter information that generates the smallest number of matches. This makes the search more efficient, and makes it easier for the user to select the final address.
The returned suggestions may have one or more of the following properties:
- Suggestions can be 'stepped into' to produce a new list of suggestions.
- Suggestions contain 'informational' items.
- Suggestions update as the user enters more characters in the search field.
Fuzzy matching
Typedown searching does not have fuzzy matching capability. Therefore, if you misspell an address element when searching for an address in Typedown, our service will not be able to find it.
Methods
This is a multi-step process involving the following endpoints:
- Search for an address, starting with the most generic information. This will provide a selection of full and/or partial addresses to choose from.
- POST /address/search/v1: Set the
search_type to typedown via the options array.
- Should the response contain a list of suggestions that need further refinement, you can drill down further by stepping into a suggestion or providing a refinement.
- GET /address/suggestions/stepin/v1/{global_address_key}: Step-in allows a user to select a suggestion and 'step into' it to obtain more detailed suggestions.
- POST /address/suggestions/refine/v1/{global_address_key}: The user is able to provide additional information for the request, for example to select a single building from building numbers returned in a range.
- Repeat the above step as often as necessary until a full address is selected.
- Format the selected address, using the 'global address key'. You can choose between:
- GET /address/format/v1/{global_address_key}: Formats an address into the standard 7 line global layout, thereby creating a well formatted address for every country and territory.
- POST /address/format/v1/{global_address_key}: Formats an address into one of your available custom layouts.
Enrichment data
You can include enrichment data by adding the relevant layout to the /format endpoint. Please contact us if you would like to purchase Enrichment data.
Recommended implementation
- The user starts to type into the single text box. Suggestions will be displayed in a drop-down.
- Optionally, the user can either:
- Continue to type for a more accurate selection in the drop-down.
- Provide a refinement for one of the suggestions to create a new list of suggestions (for example, providing a more specific address component like a street or building number).
- Step into one of the suggestions to obtain a list of more detailed suggestions.
- Repeat the above step as often as necessary until a full address is selected.
- Select a full address from the results.
- When a selection is made, the final address is displayed and any optional enrichment information shown per your website design i.e. a single text box or a multi-fielded layout.
The recommended workflow (as demonstrated by our sample code) is:
The relevant address and enrichment components can be stored in your database if required.
