Documentation

Address API - Address Suggestions


Overview

The Address Suggestions API enhances the address entry experience by providing real-time address suggestions based on user input. It helps improve the accuracy and speed of address entry by suggesting possible addresses as users type. It supports multiple address providers to ensure comprehensive and reliable address data (Google Maps, Loqate).

Ingrid Checkout Widget Address Suggestions

The Ingrid Checkout Widget integrates the Address Suggestions API to provide users with real-time address suggestions during the checkout process. As users begin typing their address, the widget displays a list of suggested addresses, allowing users to quickly select the correct address without needing to type the full details.

Ingrid Checkout Widget - Address Suggestions

Suggest Addresses

Suggest addresses based on user input to enhance the address entry experience. Used to provide real-time address suggestions as users type, improving accuracy and speed of address entry.

First, make a request to the ListSuggestions endpoint with the user's input query. For example when user in the UK searches for "Borough Hill", call GET /suggestions?customer_search_input=Borough%20Hill&country=GB&provider=LOQATE.

As a response, you will receive a list of suggested addresses matching the input query. Suggested address can come in two formats:

[
  {
    "container_id": "gb-rm|tF-4JZsBvW1nq0s0GSOz",
    "display_line_1": "Borough Hill",
    "display_line_2": "Daventry NN11 - 4 Addresses",
    "provider": "LOQATE"
  },
  {
    "id": "GB|RM|A|6026952|ENG",
    "display_line_1": "Borough Hill Farm",
    "display_line_2": "Barcheston Shipston-on-Stour CV36 5AZ",
    "provider": "LOQATE"
  }
]

With id or with container_id.

For addresses with id, you can directly fetch the full address details using the ConvertSuggestion endpoint (/suggestions/{id}:convert).

For addresses with container_id, you need to first retrieve the next round of suggestions using the ListSuggestions endpoint (/suggestions?container_id={container_id}), when user selects that suggestion, until you reach a suggestion with an id that can be converted to a full address.


curl https://api-stage.ingrid.com/address/v1/suggestions?customer_search_input=Borough%20Hill&country=UK&provider=LOQATE \
-X GET \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $PRIVATE_KEY_BASE64"

GET https://api-stage.ingrid.com/address/v1/suggestions?customer_search_input=Borough%20Hill&country=GB&provider=LOQATE
Authorization: Bearer $PRIVATE_KEY_BASE64
Content-Type: application/json


{
  "suggestions": [
    {
      "container_id": "gb-rm|tF-4JZsBvW1nq0s0GSOz",
      "display_line_1": "Borough Hill",
      "display_line_2": "Daventry NN11 - 4 Addresses",
      "provider": "LOQATE"
    },
    {
      "container_id": "gb-rm|Xna_JZsBvW1nq0s0P2Ya",
      "display_line_1": "Borough Hill Farm Catton Road",
      "display_line_2": "Walton-on-Trent Swadlincote DE12 8LL - 12 Addresses",
      "provider": "LOQATE"
    },
    {
      "container_id": "gb-rm|o4TDJZsBvW1nq0s0qLd3",
      "display_line_1": "Borough Hill",
      "display_line_2": "Petersfield GU32 3LQ - 20 Addresses",
      "provider": "LOQATE"
    },
    {
      "container_id": "gb-rm|zFy3JZsBvW1nq0s0QVL8",
      "display_line_1": "Borough Hill",
      "display_line_2": "Croydon CR0 - 91 Addresses",
      "provider": "LOQATE"
    },
    {
      "id": "GB|RM|A|4964522|ENG",
      "display_line_1": "Borough Hill Bolford Street",
      "display_line_2": "Thaxted Dunmow CM6 2PY",
      "provider": "LOQATE"
    },
    {
      "id": "GB|RM|A|6026952|ENG",
      "display_line_1": "Borough Hill Farm",
      "display_line_2": "Barcheston Shipston-on-Stour CV36 5AZ",
      "provider": "LOQATE"
    },
    {
      "id": "GB|RM|A|6606234|ENG",
      "display_line_1": "Borough Hill Farm Catton Road",
      "display_line_2": "Walton-on-Trent Swadlincote DE12 8LL",
      "provider": "LOQATE"
    },
    {
      "id": "GB|RM|A|16980155|ENG",
      "display_line_1": "Borough Hill Farm London Road",
      "display_line_2": "Daventry NN11 4NG",
      "provider": "LOQATE"
    },
    {
      "id": "GB|RM|A|6606235|ENG",
      "display_line_1": "Borough Hill Cottage Catton Road",
      "display_line_2": "Walton-on-Trent Swadlincote DE12 8LL",
      "provider": "LOQATE"
    }
  ]
}

Convert Suggestion to Full Address

Convert a selected address suggestion into a full address. Used to retrieve complete address details after a user selects an address suggestion during the address entry process.


curl https://api-stage.ingrid.com/address/v1/suggestions/GB%7CRM%7CA%7C6026952%7CENG:convert?provider=LOQATE \
-X GET \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $PRIVATE_KEY_BASE64"

GET https://api-stage.ingrid.com/address/v1/suggestions/GB%7CRM%7CA%7C6026952%7CENG:convert?provider=LOQATE
Authorization: Bearer $PRIVATE_KEY_BASE64
Content-Type: application/json


{
  "address": {
    "country_code": "GB",
    "region_code": "ENG",
    "postal_code": "CV36 5AZ",
    "city": "Shipston-on-Stour",
    "address_lines": [
      "Barcheston, Borough Hill Farm",
      "Borough Hill Farm"
    ],
    "building_name": "Borough Hill Farm"
  }
}

Last updated: Thu, Feb 12, 06:59 AM