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.


This is a multi-step process involving the following endpoints:

  1. 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.
  2. 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.
  3. Repeat the above step as often as necessary until a full address is selected.
  4. 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.

Recommended implementation

  1. The user starts to type into the single text box. Suggestions will be displayed in a drop-down.
  2. 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.
  3. Repeat the above step as often as necessary until a full address is selected.
  4. Select a full address from the results.
  5. 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.

Typedown sequence diagram, showing address refinement starting from the most general address component.

The recommended workflow (as demonstrated by our sample code) is:

Typedown developer workflow showing the API calls, inegration actions, and user actions to get from a general address component input to a final complete address.

The relevant address and enrichment components can be stored in your database if required.