What are freeform and structured addresses? (API)

Addresses on profiles have two types:

  • STRUCTURED (recommended): This address is structured into its individual components (e.g. postal code, locality, street number). Data providers use this type.
  • FREEFORM (not recommended): This address is made up of a country (provided as an ISO3 country code) and a free text field that contains the rest of the address. Data providers cannot use this type.

If you send PassFort a FREEFORM address, we'll convert it to a STRUCTURED address automatically so we can send it to the data provider to run the check. However, this conversion process can result in incorrect addresses.

For this reason, we always recommend you send us STRUCTURED addresses in your live environment.

To learn about the tools you can use to allow your customers to enter addresses in an unstructured way, see Capturing unstructured addresses.

A profile's address is stored in its COLLECTED_DATA (collected_data.address_history.address for individual profiles and collected_data.metadata.addresses for company profiles) . To learn more, see the Get collected data Developer Resources.

Structured address fields

Parameters

The following parameters are used in STRUCTURED addresses.

Key

Value

Description

type

Required

String

STRUCTURED

The address type.

country

Required

String

Sample value: GBR

The country must be provided as an ISO3 code.

The country of the address.

county

Optional

String

Sample value: Middlesex

The county of the address.

Note that a US state or a Canadian province or territory should not go here.

locality

Optional

String

Sample value: London

The city or town of the address.

original_freeform_address

Optional

String

Sample value: , , 38, Crown Street, London, , Middlesex, , W1 2ZT

The freeform address, prior to structuring attempts.

original_structured_address

Optional

Object

For a sample value, see the Example below.

This field is deprecated and is not used.

It contains the same data as the rest of the structured address.

postal_code

Optional

String

Sample value: W1 2ZT

The postal code or zip code of the address.

postal_town

Optional

String

Sample value: London

The postal town or district of the address.

premise

Optional

String

Sample value: Princelet House

The name of the building.

route

Optional

String

Sample value: Crown Street

The name of the route or street.

state_province

Required (US and Canada only)

String

Sample value: Ontario

The US state or the Canadian province or territory of the address.

Note that a UK county should not go here.

street_number

Optional

String

Sample value: 38

The street number of the address.

subpremise

Optional

String

Sample value: Flat C

The subaddress within the building. Typically this is a flat number.

Example

This is an example of a STRUCTURED address.

{
"type": "STRUCTURED",
"country": "GBR",
"county": "Middlesex",
"locality": "London",
"original_freeform_address": ", , 38, Crown Street, London, , Middlesex, , W1 2ZT",
"original_structured_address": {
"country": "GBR",
"county": "Middlesex",
"locality": "London",
"postal_code": "W1 2ZT",
"postal_town": "",
"premise": "",
"route": "Crown Street",
"state_province": "",
"street_number": "38",
"subpremise": ""
}
"postal_code": "W1 2ZT",
"postal_town": "",
"premise": "",
"route": "Crown Street",
"state_province": "",
"street_number": "38",
"subpremise": ""
}

Freeform addresses fields

We strongly recommend using the tools in Capturing unstructured addresses rather than sending FREEFORM addresses.

Parameters

The following parameters are used in FREEFORM addresses.

Key

Value

Description

type

Required

String

FREEFORM

The address type.

country

Required

String

Sample value: GBR

The country must be provided as an ISO3 code.

The country of the address.

text

Required

String

Sample value: , , 38, Crown Street, London, , Middlesex, , W1 2ZT

A free text description of the address.

Example

This is an example of the STRUCTURED address above written as a FREEFORM address.

{
"type": "FREEFORM",
"country": "GBR",
"text": ", , 38, Crown Street, London, , Middlesex, , W1 2ZT"
}

Capturing unstructured addresses

If you're enabling your customers to enter addresses in an unstructured way, there are several tools you can use to convert them to STRUCTURED addresses.

We've given two examples of tools for this conversion, but you can use any option that suits you.

GBGroup Loqate

GBGroup Loqate might be the right option for you. If it is, you can use PassFort as a reseller.

When you use GBGroup Loqate, the fields will be mapped for you as follows.

GBGroup Loqate field

PassFort profile address field

CountryIso3

country

City

locality

PostalCode

postal_code

District

postal_town

BuildingName

premise

Street

route

ProvinceCode

state_province

BuildingNumber

street_number

SubBuilding

subpremise

To learn more about how it works, see the Address Search Developer Resources.

To add this configuration to your account, contact us.

When you use PassFort as a reseller, you can use PassFort credit to pay for address formatting.

Google Maps

You can use the Google Maps Autocomplete for Addresses and Search Terms API to capture STRUCTURED addresses.

The API offers javascript widgets that you may find easier to implement.

Map the fields from Google Map's address_components array as follows.

Google Maps address_components field

PassFort profile address field

country

Note that you'll need to convert this field from an Alpha-2 code to an Alpha-3 (ISO3) code.

country

locality

locality

postal_code

postal_code

postal_town

postal_town

premise

premise

route

route

administrative_area_level_1

state_province

street_number

street_number

subpremise

subpremise


How did we do?


Powered by HelpDocs