Suggestions/Refine

When a search has been performed by our service, the list of suggestions that is returned may contain suggestions where the multiple property is set to true. Should a user select one of these addresses, the user must be prompted to enter a refinement string.

• Request
• Response
• Status codes
• Examples

{
  "result": {
    "more_results_available": false,
    "confidence": "Multiple matches",
    "suggestions_key": "i5BQUFBQUFBQUFBQUFBQUFBQUFBLX4xM343",
    "suggestions_prompt": "Enter selection",
    "suggestions": [
      {
        "global_address_key": "EuMGdVQUFRQUFBR0p5YVhOaVlXNWxBQS0tfjl-Nw",
        "text": "EAST BRISBANE  QLD  4169",
        "additional_attributes": [
          { "name": "picklist_display", "value": "EAST BRISBANE  QLD" },
          { "name": "score", "value": "100" },
          { "name": "postcode", "value": "4169" },
          { "name": "can_step_in", "value": "true" },
          { "name": "multiples", "value": "true" },
          { "name": "alias_match", "value": "true" }
        ]
      },
      {
        "global_address_key": "UFBQUQuLjJRQUFBQUEuLi4uLndBQUFBQUFBQU",
        "text": "COORPAROO  QLD  4151",
        "additional_attributes": [
          { "name": "picklist_display", "value": "COORPAROO  QLD" },
          { "name": "score", "value": "0" },
          { "name": "can_step_in", "value": "true" },
          { "name": "multiples", "value": "true" },
          { "name": "alias_match", "value": "true" }
          { "name": "cross_border_match", "value": "true" },
        ]
      }
    ]
  }
}

POST /address/suggestions/refine/v1/EuMGdVQUFRQUFBR0p5YVhOaVlXNWxBQS0tfjl-Nw HTTP/1.1

{
    "refinement": "ba"
}

{
  "result": {
    "more_results_available": false,
    "confidence": "Multiple matches",
    "suggestions_key": "osnfuJjdT-ergergUIGLKE54",
    "suggestions_prompt": "Enter street name or PO Box type",
    "suggestions": [
      {
        "global_address_key": "BQVltRUFBQUFBQUEtLX4xMX43",
        "text": "Balmoral Terrace, EAST BRISBANE  QLD  4169",
        "additional_attributes": [
          { "name": "picklist_display", "value": "Balmoral Terrace" },
          { "name": "score", "value": "0" },
          { "name": "postcode", "value": "4169" },
          { "name": "can_step_in", "value": "true" },
          { "name": "multiples", "value": "true" }
        ]
      },
      {
        "global_address_key": "UFBQW5YTVNwaEJGR0FJWUFDQUFBQUFBQUFBQUFQLi5BQUFBQUFELi",
        "text": "Barker Street, EAST BRISBANE  QLD  4169",
        "additional_attributes": [
          { "name": "picklist_display", "value": "Barker Street" },
          { "name": "score", "value": "0" },
          { "name": "postcode", "value": "4169" },
          { "name": "can_step_in", "value": "true" },
          { "name": "multiples", "value": "true" }
        ]
      },
      {
        "global_address_key": "QVVTfjcuNzMwWk9BVVNI",
        "text": "Bates Court, EAST BRISBANE  QLD  4169",
        "additional_attributes": [
          { "name": "picklist_display", "value": "Bates Court" },
          { "name": "score", "value": "0" },
          { "name": "postcode", "value": "4169" },
          { "name": "can_step_in", "value": "true" },
          { "name": "multiples", "value": "true" }
        ]
      }
    ]
  }
}

{
  "result": {
    "more_results_available": true,
    "confidence": "Multiple matches",
    "suggestions_key": "QUFBQUFRbUZzYlc5eVlXd2dWR1Z5Y2",
    "suggestions_prompt": "Enter building number/name",
    "suggestions": [
      {
        "global_address_key": "BQUFBQUFBQUFBQUFBQX40Mn43",
        "text": "22 Balmoral Terrace, EAST BRISBANE  QLD  4169",
        "additional_attributes": [
          { "name": "picklist_display", "value": "22" },
          { "name": "score", "value": "0" },
          { "name": "can_step_in", "value": "true" },
          { "name": "multiples", "value": "true" }
        ]
      },
      {
        "global_address_key": "QUFBQUFBQUFBQUF-MTF-Nw",
        "text": "24 ... 31 Balmoral Terrace, EAST BRISBANE  QLD  4169",
        "additional_attributes": [
          { "name": "picklist_display", "value": "24 ... 31" },
          { "name": "score", "value": "0" },
          { "name": "can_step_in", "value": "true" },
          { "name": "multiples", "value": "true" }
        ]
      }
    ]
  }
}

POST /address/suggestions/refine/v1/QUFBQUFRbUZzYlc5eVlXd2dWR1Z5Y2 HTTP/1.1

{
    "refinement": "29"
}

{
  "result": {
    "more_results_available": false,
    "confidence": "Verified match",
    "suggestions_key": "TUNaaEJGZ0FJQUFBQUFBQUFBQUFELi53QU",
    "suggestions_prompt": "Enter building number",
    "suggestions": [
      {
        "global_address_key": "FBQUFBQU1qa0FBQUFBQUEtLX4xM343",
        "text": "29 Balmoral Terrace, EAST BRISBANE  QLD  4169",
        "format": "https://api.experianaperture.io/address/format/v1/FBQUFBQU1qa0FBQUFBQUEtLX4xM343",
        "additional_attributes": [
          { "name": "picklist_display", "value": "29" },
          { "name": "score", "value": "0" },
          { "name": "full_address", "value": "true" }
        ]
      }
    ]
  }
}

{
  "result": {
    "more_results_available": false,
    "confidence": "Multiple matches",
    "suggestions_key": "R0JSfjcuNzMwTk1HQlJ",
    "suggestions_prompt": "Enter selection",
    "suggestions": [
      {
        "global_address_key": "BQUFBQUFBQUFBQUFBQUFBQX41fjc",
        "text": "DOVER, Kent",
        "additional_attributes": [
          { "name": "picklist_display", "value": "DOVER, Kent" },
          { "name": "score", "value": "100" },
          { "name": "can_step_in", "value": "true" },
          { "name": "multiples", "value": "true" }
        ]
      },
      {
        "global_address_key": "LjJRQUFBQUEuLi4uLndBQUFBQUFBQUF",
        "text": "Kearsney, DOVER, Kent",
        "additional_attributes": [
          { "name": "picklist_display", "value": "Kearsney, DOVER, Kent" },
          { "name": "score", "value": "100" },
          { "name": "can_step_in", "value": "true" },
          { "name": "multiples", "value": "true" }
        ]
      }
    ]
  }
}

POST /address/suggestions/refine/v1/BQUFBQUFBQUFBQUFBQUFBQX41fjc HTTP/1.1

{
    "refinement": "mil"
}

{
  "result": {
    "more_results_available": true,
    "confidence": "Multiple matches",
    "suggestions_key": "R0JSfjcuNzMwVk9HQlJFZ0xtQndBQUFBQUJBQ",
    "suggestions_prompt": "Enter street, organisation or PO Box",
    "suggestions": [
      {
        "global_address_key": "VBQUFBQXNlbHVrWUFoZ0FJQUFBQUFB",
        "text": "Mill Close, DOVER, Kent",
        "format": "https://api.experianaperture.io/address/format/v1/VBQUFBQXNlbHVrWUFoZ0FJQUFBQUFB",
        "additional_attributes": [
          { "name": "picklist_display", "value": "Mill Close" },
          { "name": "score", "value": "0" },
          { "name": "can_step_in", "value": "true" },
          { "name": "multiples", "value": "true" }
        ]
      },
      {
        "global_address_key": "R0JSfjcuNzMwOU9HQlJFZ0xtQndBQU",
        "text": "Military Road, DOVER, Kent",
        "format": "https://api.experianaperture.io/address/format/v1/R0JSfjcuNzMwOU9HQlJFZ0xtQndBQU",
        "additional_attributes": [
          { "name": "picklist_display", "value": "Military Road" },
          { "name": "score", "value": "0" },
          { "name": "can_step_in", "value": "true" },
          { "name": "multiples", "value": "true" }
        ]
      }
    ]
  }
}

{
  "result": {
    "more_results_available": false,
    "confidence": "Multiple matches",
    "suggestions_key": "QUFBQUJBQUVBQUFBQW5IZmdVWUF",
    "suggestions_prompt": "Enter building number/name or organisation",
    "suggestions": [
      {
        "global_address_key": "zTnlBeGNtWUFBQUFBQUEtLX43fjc",
        "text": "2 ... 14 Tilebourne Close, Upper Timsbury, ROMSEY, Hampshire SO51 0AH",
        "additional_attributes": [
          { "name": "picklist_display", "value": "2 ... 14   [even]" },
          { "name": "score", "value": "0" },
          { "name": "can_step_in", "value": "true" },
          { "name": "multiples", "value": "true" }
        ]
      },
      {
        "global_address_key": "kjhTYufsLlid8ljhd",
        "text": "1 ... 13 Tilebourne Close, Upper Timsbury, ROMSEY, Hampshire SO51 0AH",
        "additional_attributes": [
          { "name": "picklist_display", "value": "1 ... 13   [odd]" },
          { "name": "score", "value": "0" },
          { "name": "can_step_in", "value": "true" },
          { "name": "multiples", "value": "true" }
        ]
      }
    ]
  }
}

POST /address/suggestions/refine/v1/QUFBQUJBQUVBQUFBQW5IZmdVWUF HTTP/1.1

{
    "refinement": "10"
}

{
  "result": {
    "more_results_available": true,
    "confidence": "Verified match",
    "suggestions_key": "R0JSfjcuNzMwc09HQlJFZ0xtQndBQU",
    "suggestions_prompt": "Enter building number",
    "suggestions": [
      {
        "global_address_key": "FBQUFBQUFNVEFBQVAuLkFBQUFBQUQuLi4uLkFBQ",
        "text": "10 Tilebourne Close, Upper Timsbury, ROMSEY, Hampshire SO51 0AH",
        "format": "https://api.experianaperture.io/address/format/v1/FBQUFBQUFNVEFBQVAuLkFBQUFBQUQuLi4uLkFBQ",
        "additional_attributes": [
          { "name": "picklist_display", "value": "10" },
          { "name": "score", "value": "0" },
          { "name": "full_address", "value": "true" }
        ]
      }
    ]
  }
}

{
  "result": {
    "more_results_available": false,
    "confidence": "Multiple matches",
    "suggestions_key": "78JKHGiou23088djkhKHG987shgGBFd1",
    "suggestions_prompt": "Enter building number/name or organisation",
    "suggestions": [
      {
        "global_address_key": "QUFBQUEuLi4uLndBQUFBQUFBQUFBQUFBQ",
        "text": "Richmond, Ocean Ridge FL 33435",
        "additional_attributes": [
          { "name": "picklist_display", "value": "Richmond, Ocean Ridge FL" },
          { "name": "score", "value": "100" },
          { "name": "postcode", "value": "33435" },
          { "name": "can_step_in", "value": "true" },
          { "name": "multiples", "value": "true" }
        ]
      },
      {
        "global_address_key": "zMwRVRVU0FEd1BtQndBQUFBQUNBUUFBQUFBQUFBRUFBQURmcU",
        "text": "Richmondville NY 12149",
        "additional_attributes": [
          { "name": "picklist_display", "value": "Richmondville NY" },
          { "name": "score", "value": "100" },
          { "name": "postcode", "value": "12149" },
          { "name": "can_step_in", "value": "true" },
          { "name": "multiples", "value": "true" }
        ]
      }
    ]
  }
}

POST /address/suggestions/refine/v1/zMwRVRVU0FEd1BtQndBQUFBQUNBUUFBQUFBQUFBRUFBQURmcU HTTP/1.1

{
    "refinement": "de"
}

{
  "result": {
    "more_results_available": true,
    "confidence": "Multiple matches",
    "suggestions_key": "cUJ3QUFBQUFBRkpKUTBoTlQwNUVBQS0tfjExfjc",
    "suggestions_prompt": "Enter street name, organisation or PO Box type",
    "suggestions": [
      {
        "global_address_key": "d2doR0FJWUFDQUFBQUFBQUFBQUF",
        "text": "Decker Rd, Richmondville NY 12149",
        "additional_attributes": [
          { "name": "picklist_display", "value": "Decker Rd, Richmondville NY" },
          { "name": "score", "value": "0" },
          { "name": "postcode", "value": "12149" },
          { "name": "can_step_in", "value": "true" },
          { "name": "multiples", "value": "true" }
        ]
      },
      {
        "global_address_key": "RnpBQUFBQUFBLX4xMX43",
        "text": "Depot St, Richmondville NY 12149",
        "additional_attributes": [
          { "name": "picklist_display", "value": "Depot St, Richmondville NY" },
          { "name": "score", "value": "0" },
          { "name": "postcode", "value": "12149" },
          { "name": "can_step_in", "value": "true" },
          { "name": "multiples", "value": "true" }
        ]
      }
    ]
  }
}

{
  "result": {
    "more_results_available": false,
    "confidence": "Multiple matches",
    "suggestions_key": "VVNBfjcuNzMwaE9VU0FEd1BtQndBQUFBQUJBQUVB",
    "suggestions_prompt": "Enter building number/name or organisation",
    "suggestions": [
      {
        "global_address_key": "ndBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQX4yNH43",
        "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": "VVNBfjcuNzMwdk9VU0FEd1BtQndBQUFBQUJBZ0V",
        "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-9589" },
          { "name": "multiples", "value": "true" },
          { "name": "unresolvable_range", "value": "true" }
        ]
      }
    ]
  }
}

POST /address/suggestions/refine/v1/SnNaWE1nVTNSeVpXVjBMQ0JTU1VOSVRVOU9SQUFBQUFBQX4yNH43 HTTP/1.1

{
    "refinement": "10111"
}

{
  "result": {
    "more_results_available": false,
    "confidence": "Verified match",
    "suggestions_key": "BQUFBQX4yOX43",
    "suggestions_prompt": "Enter building number/name or organisation",
    "suggestions": [
      {
        "global_address_key": "VVNBfjcuNzMwTk9VU0FEd1BtQnd",
        "text": "10111 Charles St, Richmond IL 60071-9590",
        "format": "https://api.experianaperture.io/address/format/v1/VVNBfjcuNzMwTk9VU0FEd1BtQnd",
        "additional_attributes": [
          { "name": "picklist_display", "value": "10111" },
          { "name": "score", "value": "0" },
          { "name": "postcode", "value": "60071-9590" },
          { "name": "full_address", "value": "true" }
        ]
      }
    ]
  }
}