Structured Request - Beta

One of the things which can improve search accuracy and speed the most is a parsed address. Consider the address "25 Lower Way, Thatcham RG19 3RR". For a computer this is just a meaningless string, and can easily be confused with other similar strings. However, consider the following JSON

{
  "street_number": "25",
  "street_name": "Lower Way",
  "city": "Thatcham",
  "postalcode": "RG19 3RR"
}

This is much easier and faster to search. Therefore, we now offer a second way to include an address, by using the address_structured field. Which can take the following JSON

{
    "address_line": Option<String>,
    "unit": Option<String>,
    "house_name": Option<String>,
    "street_number": Option<String>,
    "street_name": Option<String>,
    "city": Option<String>,
    "county": Option<String>,
    "state": Option<String>,
    "country": Option<String>,
    "postalcode": Option<String>
}

All fields are optional, however you must include enough fields to make a fully qualified address. There are two mutually exclusive ways to make a fully qualified address. Both of these options are subject to change.

Option 1: a street_name, a postalcode and either a house_name or street_number (or both) at minimum.

Option 2: A postalcode and an address_line at minimum.

address_line is mutually exclusive with any of unit, house_name, street_number and street_name.

You can use any other options as discussed in this documentation. For example, a full request might be

{
  "address_structured": {
    "street_number": "25",
    "street_name": "Lower Way",
    "city": "Thatcham",
    "postalcode": "RG19 3RR"
  },
  "lat": 51.4019,
  "lon": -1.2687,
  "additional_matches": true
}

You may not use address_string and address_structured at the same time. This would return a 400:

{
  "address_string": "25 Lower Way, Thatcham, RH19 3RR",
  "address_structured": {
    "street_number": "25",
    "street_name": "Lower Way",
    "city": "Thatcham",
    "postalcode": "RG19 3RR"
  },
  "lat": 51.4019,
  "lon": -1.2687,
  "additional_matches": true
}

Let's also look at some examples of what kind of data goes into which field.

• Unit: a flat, apartment, suite or unit number e.g. "flat 6", "building C", "unit 2"
• House name: a named building e.g. "Buckingham Palace", "Pearl Court", "Falmer House"
• Street Number: the number on the street e.g. "2", "25", "1015"
• Street Name: the name of the street e.g. "Yew Court Road", "3rd Ave", "Mount Rosie Rd"
• City: the name of the city, or town, village, hamlet e.g. "London", "Bradpole", "Catskill"
• County: county name e.g. "Sussex", "Berkshire", "Mid Glamorgan"
• State: state name e.g. "Texas", "California", "Maine"
• Country: country e.g. "USA", "UK", "Singapore"
• Postalcode: postcode or Zip code e.g. "BN21 4LD", "128130", "33607"

Some notes:

• County is not commonly used in USA addresses, but very common in UK addresses. In the USA this would be counties like "Alameda", "Miami Dade", "Cook". Again, rarely used in USA addresses
• State, in the USA is the states, which are common on addresses (Texas, New York and so on). In the UK, state refers to the constituent nations i.e. "England", "Scotland", "Wales", "Northern Ireland". Not commonly used in UK addresses
• Country is unnecessary in the structured address if the country tag is used in the base request. In the base request, country can only take official two digit country codes i.e. UK, SG, US. In the structured address, it can take any arbitrary country string e.g. "United Kingdom", "United States of America", "America", "United States" and so on.
• Postalcode is known as Zip code in the USA. You can use a standard Zip code e.g. "80236", or a Zip+4 code e.g. "80236-2345"

Let's finally look at some examples of what some correctly parsed examples would look like

In the UK a typical address could be

123 Valley Way
Stevenage
Hertfordshire
SG2 9DE

Which would be correctly parsed as

{
  "street_number": "123",
  "street_name": "Valley Way",
  "city": "Stevenage",
  "county": "Hertfordshire",
  "postalcode": "SG2 9DE"
}

In the USA a typical address could be

143-10 94th Ave
Jamaica, NY 11435

Which would be correctly parsed as

{
  "street_number": "143-10",
  "street_name": "94th Ave",
  "city": "Jamaica",
  "state": "NY",
  "postalcode": "11435"
}

Note how street number is a string not a number, as many street numbers are not numbers! Also, in the USA you may use full state names or abbreviations e.g. Texas or TX.

In Singapore a typical address might be

Blk 123 Bishan St 12 #04-56
Singapore 570123

Which would be correctly parsed as

{
  "unit": "#04-56",
  "street_number": "Blk 123",
  "street_name": "Bishan St 12",
  "city": "Singapore",
  "postalcode": "570123"
}

Singapore could also go in the country field here, the search would work it out either way. You can also always use SG in the root country field to speed up search even more, if you know the address is in Singapore!

address_line is what is often used as "address line 1" in mailing forms. This will typically include a street number, street name, and maybe a unit and house name. If we return to our examples above we can repeat for the address_line

123 Valley Way
Stevenage
Hertfordshire
SG2 9DE

The address line here is 123 Valley Way

143-10 94th Ave
Jamaica, NY 11435

The address line here is 143-10 94th Ave

Blk 123 Bishan St 12 #04-56
Singapore 570123

The address line here is Blk 123 Bishan St 12 #04-56