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

PassFort portal name

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.

Country

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.

County

locality

Optional

String

Sample value: London

The city or town of the address.

City

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 code

postal_town

Optional

String

Sample value: London

The postal town or district of the address.

Town

premise

Optional

String

Sample value: Princelet House

The name of the building.

Building name

route

Optional

String

Sample value: Crown Street

The name of the route or street.

Street

state_province

Required (US, Canada, Australia)

Optional (all other countries)

String

Sample value: ON

The state, province, or territory of the address.

The format follows the state code of the ISO-3166-2 standard.

Note that a UK county should not go here.

State

street_number

Optional

String

Sample value: 38

The street number of the address.

Building number

subpremise

Optional

String

Sample value: Flat C

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

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 a few examples of tools for this conversion, but you can use any option that suits you.

Experian Data Quality

When you use Experian Data Quality, the fields will be mapped as follows.

Experian Data Quality field

PassFort profile address field

countryISO1

country

locality1

locality

postalCode1

postal_code

locality2

postal_town

building1 or organisation1

premise

street1

route

provinceCode1

state_province

county1

county

streetNumber1

street_number

subBuilding1

subpremise

GBG Loqate

If GBG Loqate is the right option for you, you can use PassFort as a reseller.

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

GBG 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 (opens in a new tab)