Suggestions/Stepin

Request

The /Suggestions/Stepin method can be used in your addess validation workflow to produce a list of suggestions that contains more detail than the current item, e.g. a suggestion that represents a street can be stepped into to produce a new list of suggestions that contain premises within the street.

Given the response contains the following suggestion:

{
  "global_address_key": "dWc1ltOTFjbTVsQUEtLX45fjc",
  "text": "Mary Street, HAWTHORN  VIC  3122",
  "additional_attributes": [
    { "name": "picklist_display", "value": "Mary Street, HAWTHORN  VIC" },
    { "name": "score", "value": "100" },
    { "name": "postcode", "value": "3122" },
    { "name": "can_step_in", "value": "true" },
    { "name": "multiples", "value": "true" }
  ]
}

You can step into it to produce a list of premises within Mary Street by passing the returned global_address_key to the /Suggestions/Stepin method:

GET /address/suggestions/stepin/v1/dWc1ltOTFjbTVsQUEtLX45fjc HTTP/1.1

Response

The returned list of suggestions can include full addresses as well as items that need further steping into or refinement.

{
  "result": {
    "more_results_available": true,
    "confidence": "Multiple matches",
    "suggestions_key": "VBQUFBQkxkYktKaEVBQlJHQUlBQUFB",
    "suggestions_prompt": "Enter building number/name",
    "suggestions": [
      {
        "global_address_key": "UFBQUFBQUFBQUFBQUFBQS0tfjIxfjc",
        "text": "1 ... 5 Mary Street, HAWTHORN  VIC  3122",
        "additional_attributes": [
          { "name": "picklist_display", "value": "1 ... 5" },
          { "name": "score", "value": "0" },
          { "name": "can_step_in", "value": "true" },
          { "name": "multiples", "value": "true" }
        ]
      },
      {
        "global_address_key": "QVVTfjcuNzMwNU9BVVNIQVBtQnd",
        "text": "21a Mary Street, HAWTHORN  VIC  3122",
        "format": "https://api.experianaperture.io/address/format/v1/QVVTfjcuNzMwNU9BVVNIQVBtQnd",
        "additional_attributes": [
          { "name": "picklist_display", "value": "21a" },
          { "name": "score", "value": "0" },
          { "name": "full_address", "value": "true" }
        ]
      }
    ]
  }
}

Request

The /Suggestions/Stepin method can be used in your addess validation workflow to produce a list of suggestions that contains more detail than the current item, e.g. a suggestion that represents a street can be stepped into to produce a new list of suggestions that contain premises within the street.

Given the response contains the following suggestion:

{
  "global_address_key": "zTnlBeGNtWUFBQUFBQUEtLX43fjc",
  "text": "Valley Road, PLYMOUTH PL7 1RF",
  "additional_attributes": [
    { "name": "picklist_display", "value": "Valley Road, PLYMOUTH" },
    { "name": "score", "value": "100" },
    { "name": "postcode", "value": "PL7 1RF" },
    { "name": "can_step_in", "value": "true" },
    { "name": "multiples", "value": "true" }
  ]
}

You can step into the it to produce a list of premises within Valley Road by passing the returned global_address_key to the /Suggestions/Stepin method:

GET /address/suggestions/stepin/v1/zTnlBeGNtWUFBQUFBQUEtLX43fjc HTTP/1.1
Host: api.experianaperture.io
Content-Type: application/json

Response

The returned list of suggestions can include full addresses as well as items that need further steping into or refinement.

{
  "result": {
    "more_results_available": true,
    "confidence": "Multiple matches",
    "suggestions_key": "R0JSfjcuNzMwRU9HQlJFZ0xtQndBQUFBQUJBQUVBQUFBQVkwWlRrZ0FnQ",
    "suggestions_prompt": "Enter building number/name or organisation",
    "suggestions": [
      {
        "global_address_key": "R0JSfjcuNzMwOU9HQlJFZ0xtQndBQU",
        "text": "Wise Road Management Ltd, Valley Road, PLYMOUTH PL7 1RF",
        "format": "https://api.experianaperture.io/address/format/v1/R0JSfjcuNzMwOU9HQlJFZ0xtQndBQU",
        "additional_attributes": [
          { "name": "picklist_display", "value": "Wise Road Management Ltd" },
          { "name": "score", "value": "0" },
          { "name": "full_address", "value": "true" }
        ]
      },
      {
        "global_address_key": "BQUFBQUFBQUFBQX43fjc",
        "text": "Alan Jeffery Engineering, 1 Valley Road, PLYMOUTH PL7 1RF",
        "format": "https://api.experianaperture.io/address/format/v1/BQUFBQUFBQUFBQX43fjc",
        "additional_attributes": [
          { "name": "picklist_display", "value": "Alan Jeffery Engineering, 1" },
          { "name": "score", "value": "0" },
          { "name": "full_address", "value": "true" }
        ]
      }
    ]
  }
}

Request

The /Suggestions/Stepin method can be used in your addess validation workflow to produce a list of suggestions that contains more detail than the current item, e.g. a suggestion that represents a street can be stepped into to produce a new list of suggestions that contain premises within the street.

Given the response contains the following suggestion:

{
  "global_address_key": "pXVjBMQ0JTU1VOSVRVOU9SQUFBQUFBQX4yNH43",
  "text": "Charles St, Richmond IL 60071",
  "additional_attributes": [
    { "name": "picklist_display", "value": "Charles St, Richmond IL" },
    { "name": "score", "value": "100" },
    { "name": "postcode", "value": "60071" },
    { "name": "can_step_in", "value": "true" },
    { "name": "multiples", "value": "true" }
  ]
}

You can step into the it to produce a list of premises within Charles St by passing the returned global_address_key to the /Suggestions/Stepin method:

GET /address/suggestions/stepin/v1/pXVjBMQ0JTU1VOSVRVOU9SQUFBQUFBQX4yNH43 HTTP/1.1
Host: api.experianaperture.io
Content-Type: application/json

Response

The returned list of suggestions can include full addresses as well as items that need further steping into or refinement.

{
  "result": {
    "more_results_available": false,
    "confidence": "Multiple matches",
    "suggestions_key": "VVNBfjcuNzMwdk9VU0FEd1BtQndBQUFBQUJBQUVBQUFBQzQzT3ZVWUFoTV3",
    "suggestions_prompt": "Enter building number/name or organisation",
    "suggestions": [
      {
        "global_address_key": "VVNBfjcuNzMwbk9VU0FEd1BtQndBQUFBQUJBZ0VBQ",
        "text": "10001 ... 10099 Charles St, Richmond IL 60071-9589",
        "additional_attributes": [
          { "name": "picklist_display", "value": "10001 ... 10099   [odd]" },
          { "name": "score", "value": "0" },
          { "name": "postcode", "value": "60071-9589" },
          { "name": "multiples", "value": "true" },
          { "name": "unresolvable_range", "value": "true" }
        ]
      },
      {
        "global_address_key": "BQUFBQUFBQUFBQUFBQUFBQX4yNH43",
        "text": "10101 ... 10199 Charles St, Richmond IL 60071-9590",
        "additional_attributes": [
          { "name": "picklist_display", "value": "10101 ... 10199   [odd]" },
          { "name": "score", "value": "0" },
          { "name": "postcode", "value": "60071-9590" },
          { "name": "multiples", "value": "true" },
          { "name": "unresolvable_range", "value": "true" }
        ]
      }
    ]
  }
}

Should you encounter the below response, capture more input from the user to refine the selected suggestion.

{
  "result": {
    "more_results_available": true,
    "confidence": "Multiple matches",
    "suggestions_key": "F3QUJ3QUFBQUFBMng4TUFBQUFBQUFBQUVFZURBUEtLX45fjc",
    "suggestions_prompt": "Enter street name or PO Box type",
    "suggestions": [
      {
        "text": "Continue typing (too many matches)",
        "additional_attributes": [
          { "name": "picklist_display", "value": "Continue typing (too many matches)" },
          { "name": "score", "value": "0" },
          { "name": "information", "value": "true" }
        ]
      }
    ]
  }
}

Should you encounter the below response, capture more input from the user to refine the selected suggestion.

{
  "result": {
    "more_results_available": true,
    "confidence": "Multiple matches",
    "suggestions_key": "F3QUJ3QUFBQUFBMng4TUFBQUFBQUFBQUVFZURBUEtLX45fjc",
    "suggestions_prompt": "Enter street name, organisation or PO Box type",
    "suggestions": [
      {
        "text": "Continue typing (or select to show all matches)",
        "additional_attributes": [
          { "name": "picklist_display", "value": "Continue typing (or select to show all matches)" },
          { "name": "score", "value": "0" },
          { "name": "multiples", "value": "true" },
          { "name": "information", "value": "true" }
        ]
      }
    ]
  }
}

Should you encounter a response that only includes a single item with the can_step_in attribute set to true that is not a informational item, we suggest to have your integration step into the item automatically and display the returned suggestions.

{
  "result": {
    "more_results_available": false,
    "confidence": "Multiple matches",
    "suggestions_key": "QVVTfjcuNzMwUFRBVVNIQVBtQndBQUFBQUNBUUFBTUFBUUFBRUFBQUF1SHd3QUFBQUFBRzFsYkdKdmRYSnVaUUEtfjl-Nw",
    "suggestions_prompt": "Enter street name or PO Box type",
    "suggestions": [
      {
        "global_address_key": "QVVTfjcuNzMwWlRBVVNIQVBtQndBQUFBQUNBUUlBTUFBUUFBRUFBQUF1SHd3QUFBQUFBRzFsYkdKdmRYSnVaUUEtfjl-Nw",
        "text": "<PO Box types>",
        "additional_attributes": [
            { "name": "picklist_display", "value": "<PO Box types>" },
            { "name": "score", "value": "0" },
            { "name": "can_step_in", "value": "true" },
            { "name": "multiples", "value": "true" },
            { "name": "dummy_po_box", "value": "true" }
        ]
      }
    ]
  }
}