Parse an Address

ShipEngine uses machine learning and natural language processing (NLP) to parse addresses data from unstructured text.

Data often enters your system as unstructured text (for example: emails, SMS messages, support tickets, or other documents). ShipEngine's address recognition API saves you from parsing this text and trying to extract the useful data within it. Instead, you can simply send us the unstructured text, and we'll return whatever address data it contains.

Our machine learning models learn and improve over time, so they become more accurate and better at understanding different writing patterns.

Example

Let's say you receive an order via email. You can send the text of the email to ShipEngine and it will automatically extract the customer's address. Here's an example:

I need to send a package to my friend Amanda Miller’s house at 525 Winchester Blvd in San Jose (that's california, obviously). The zip code there is 95128.

You could send this text to ShipEngine via the PUT /v1/addresses/recognize endpoint, and it will recognize the following pieces of information:

Entity Type	Value
`person`	Amanda Miller
`address`	Amanda Miller 525 Winchester Blvd San Jose, CA 95128
`address_residential_indicator`	residential
`address_line1`	525 Winchester Blvd
`city_locality`	San Jose
`state_province`	CA
`postal_code`	95128

Supported Countries

ShipEngine NLP currently supports English text, and can recognize addresses for the following countries:

Australia
Canada
Ireland
New Zealand
United Kingdom
United States

API Sample

In the API sample below, the response has an overall score of 0.971069... which indicates a 97% confidence that it parsed the text correctly. The score value can help your application programmatically decide if any additional input or verification from your user is needed.

The entities array breaks down the recognized data further into their own individual objects and provides additional scoring on the confidence for each field.

Example Request

POST /v1/addresses/recognize HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json

{
  "text": "I need to send a package to my friend Amanda Millers house at 525 Winchester Blvd in San Jose (thats california, obviously). The zip code there is 95128."
}

curl -iX POST https://api.shipengine.com/v1/addresses/recognize \
-H 'API-Key: __YOUR_API_KEY_HERE__' \
-H 'Content-Type: application/json' \
-d '{
  "text": "I need to send a package to my friend Amanda Millers house at 525 Winchester Blvd in San Jose (thats california, obviously). The zip code there is 95128."
}'

$headers = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"
$headers.Add("Host", "api.shipengine.com")
$headers.Add("API-Key", "__YOUR_API_KEY_HERE__")
$headers.Add("Content-Type", "application/json")

$body = "{`n  `"text`": `"I need to send a package to my friend Amanda Millers house at 525 Winchester Blvd in San Jose (thats california, obviously). The zip code there is 95128.`"`n}"

$response = Invoke-RestMethod 'https://api.shipengine.com/v1/addresses/recognize' -Method 'POST' -Headers $headers -Body $body
$response | ConvertTo-Json

var myHeaders = new Headers();
myHeaders.append("Host", "api.shipengine.com");
myHeaders.append("API-Key", "__YOUR_API_KEY_HERE__");
myHeaders.append("Content-Type", "application/json");

var raw = JSON.stringify({"text":"I need to send a package to my friend Amanda Millers house at 525 Winchester Blvd in San Jose (thats california, obviously). The zip code there is 95128."});

var requestOptions = {
  method: 'POST',
  headers: myHeaders,
  body: raw,
  redirect: 'follow'
};

fetch("https://api.shipengine.com/v1/addresses/recognize", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

var request = require('request');
var options = {
  'method': 'POST',
  'url': 'https://api.shipengine.com/v1/addresses/recognize',
  'headers': {
    'Host': 'api.shipengine.com',
    'API-Key': '__YOUR_API_KEY_HERE__',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({"text":"I need to send a package to my friend Amanda Millers house at 525 Winchester Blvd in San Jose (thats california, obviously). The zip code there is 95128."})

};
request(options, function (error, response) { 
  if (error) throw new Error(error);
  console.log(response.body);
});

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.shipengine.com/v1/addresses/recognize",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS =>"{\n  \"text\": \"I need to send a package to my friend Amanda Millers house at 525 Winchester Blvd in San Jose (thats california, obviously). The zip code there is 95128.\"\n}",
  CURLOPT_HTTPHEADER => array(
    "Host: api.shipengine.com",
    "API-Key: __YOUR_API_KEY_HERE__",
    "Content-Type: application/json"
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

import requests

url = "https://api.shipengine.com/v1/addresses/recognize"

payload = "{\n  \"text\": \"I need to send a package to my friend Amanda Millers house at 525 Winchester Blvd in San Jose (thats california, obviously). The zip code there is 95128.\"\n}"
headers = {
  'Host': 'api.shipengine.com',
  'API-Key': '__YOUR_API_KEY_HERE__',
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data = payload)

print(response.text.encode('utf8'))

require "uri"
require "net/http"

url = URI("https://api.shipengine.com/v1/addresses/recognize")

https = Net::HTTP.new(url.host, url.port);
https.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Host"] = "api.shipengine.com"
request["API-Key"] = "__YOUR_API_KEY_HERE__"
request["Content-Type"] = "application/json"
request.body = "{\n  \"text\": \"I need to send a package to my friend Amanda Millers house at 525 Winchester Blvd in San Jose (thats california, obviously). The zip code there is 95128.\"\n}"

response = https.request(request)
puts response.read_body

var client = new RestClient("https://api.shipengine.com/v1/addresses/recognize");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
request.AddHeader("Host", "api.shipengine.com");
request.AddHeader("API-Key", "__YOUR_API_KEY_HERE__");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"text\": \"I need to send a package to my friend Amanda Millers house at 525 Winchester Blvd in San Jose (thats california, obviously). The zip code there is 95128.\"\n}",  ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n  \"text\": \"I need to send a package to my friend Amanda Millers house at 525 Winchester Blvd in San Jose (thats california, obviously). The zip code there is 95128.\"\n}");
Request request = new Request.Builder()
  .url("https://api.shipengine.com/v1/addresses/recognize")
  .method("POST", body)
  .addHeader("Host", "api.shipengine.com")
  .addHeader("API-Key", "__YOUR_API_KEY_HERE__")
  .addHeader("Content-Type", "application/json")
  .build();
Response response = client.newCall(request).execute();

package main

import (
  "fmt"
  "strings"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://api.shipengine.com/v1/addresses/recognize"
  method := "POST"

  payload := strings.NewReader("{\n  \"text\": \"I need to send a package to my friend Amanda Millers house at 525 Winchester Blvd in San Jose (thats california, obviously). The zip code there is 95128.\"\n}")

  client := &http.Client {
  }
  req, err := http.NewRequest(method, url, payload)

  if err != nil {
    fmt.Println(err)
  }
  req.Header.Add("Host", "api.shipengine.com")
  req.Header.Add("API-Key", "__YOUR_API_KEY_HERE__")
  req.Header.Add("Content-Type", "application/json")

  res, err := client.Do(req)
  defer res.Body.Close()
  body, err := ioutil.ReadAll(res.Body)

  fmt.Println(string(body))
}

#import <Foundation/Foundation.h>

dispatch_semaphore_t sema = dispatch_semaphore_create(0);

NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://api.shipengine.com/v1/addresses/recognize"]
  cachePolicy:NSURLRequestUseProtocolCachePolicy
  timeoutInterval:10.0];
NSDictionary *headers = @{
  @"Host": @"api.shipengine.com",
  @"API-Key": @"__YOUR_API_KEY_HERE__",
  @"Content-Type": @"application/json"
};

[request setAllHTTPHeaderFields:headers];
NSData *postData = [[NSData alloc] initWithData:[@"{\n  \"text\": \"I need to send a package to my friend Amanda Millers house at 525 Winchester Blvd in San Jose (thats california, obviously). The zip code there is 95128.\"\n}" dataUsingEncoding:NSUTF8StringEncoding]];
[request setHTTPBody:postData];

[request setHTTPMethod:@"POST"];

NSURLSession *session = [NSURLSession sharedSession];
NSURLSessionDataTask *dataTask = [session dataTaskWithRequest:request
completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) {
  if (error) {
    NSLog(@"%@", error);
  } else {
    NSHTTPURLResponse *httpResponse = (NSHTTPURLResponse *) response;
    NSError *parseError = nil;
    NSDictionary *responseDictionary = [NSJSONSerialization JSONObjectWithData:data options:0 error:&parseError];
    NSLog(@"%@",responseDictionary);
    dispatch_semaphore_signal(sema);
  }
}];
[dataTask resume];
dispatch_semaphore_wait(sema, DISPATCH_TIME_FOREVER);

import Foundation

var semaphore = DispatchSemaphore (value: 0)

let parameters = "{\n  \"text\": \"I need to send a package to my friend Amanda Millers house at 525 Winchester Blvd in San Jose (thats california, obviously). The zip code there is 95128.\"\n}"
let postData = parameters.data(using: .utf8)

var request = URLRequest(url: URL(string: "https://api.shipengine.com/v1/addresses/recognize")!,timeoutInterval: Double.infinity)
request.addValue("api.shipengine.com", forHTTPHeaderField: "Host")
request.addValue("__YOUR_API_KEY_HERE__", forHTTPHeaderField: "API-Key")
request.addValue("application/json", forHTTPHeaderField: "Content-Type")

request.httpMethod = "POST"
request.httpBody = postData

let task = URLSession.shared.dataTask(with: request) { data, response, error in 
  guard let data = data else {
    print(String(describing: error))
    return
  }
  print(String(data: data, encoding: .utf8)!)
  semaphore.signal()
}

task.resume()
semaphore.wait()

Example Response

{
    "score": 0.9710697187242877,
    "address": {
        "name": "Amanda Miller",
        "address_line1": "525 Winchester Blvd",
        "city_locality": "San Jose",
        "state_province": "CA",
        "postal_code": "95128",
        "address_residential_indicator": "yes"
    },
    "entities": [
        {
            "type": "person",
            "score": 0.9519646137063122,
            "text": "Amanda Miller",
            "start_index": 38,
            "end_index": 50,
            "result": {
                "value": "Amanda Miller"
            }
        },
        {
            "type": "residential_indicator",
            "score": 0.9519646137063122,
            "text": "house",
            "start_index": 54,
            "end_index": 58,
            "result": {
                "value": "yes"
            }
        },
        {
            "type": "address_line",
            "score": 0.9805313966503588,
            "text": "525 Winchester Blvd",
            "start_index": 63,
            "end_index": 81,
            "result": {
                "line": 1,
                "value": "525 Winchester Blvd"
            }
        },
        {
            "type": "number",
            "score": 0.9805313966503588,
            "text": "525",
            "start_index": 63,
            "end_index": 65,
            "result": {
                "type": "cardinal",
                "value": 525
            }
        },
        {
            "type": "city_locality",
            "score": 0.9805313966503588,
            "text": "San Jose",
            "start_index": 86,
            "end_index": 93,
            "result": {
                "value": "San Jose"
            }
        },
        {
            "type": "state_province",
            "score": 0.9805313966503588,
            "text": "california",
            "start_index": 103,
            "end_index": 112,
            "result": {
                "name": "California",
                "value": "CA"
            }
        },
        {
            "type": "postal_code",
            "score": 0.9519646137063122,
            "text": "95128",
            "start_index": 149,
            "end_index": 153,
            "result": {
                "value": "95128"
            }
        }
    ]
}

tip

The address object can be used in other endpoints as-is

The attributes defined in the address object are structured in the same fashion as the "ship_from" and "ship_to" objects.

Already-known fields

You can specify any already-known fields for your address object in the request. This can help you automatically define any known variables you might collect such as...

name
city_locality
state_province
postal_code
country_code

PUT /v1/addresses/recognize HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json

{
  "text": "I need to send a package to my friend Amanda Millers house at 525 Winchester Blvd in San Jose (thats california, obviously). The zip code there is 95128.",
  "address": {
    "name": "Dr. Amanda L Miller",
    "country_code": "US"
  }
}

curl -iX PUT https://api.shipengine.com/v1/addresses/recognize \
-H 'API-Key: __YOUR_API_KEY_HERE__' \
-H 'Content-Type: application/json' \
-d '{
  "text": "I need to send a package to my friend Amanda Millers house at 525 Winchester Blvd in San Jose (thats california, obviously). The zip code there is 95128.",
  "address": {
    "name": "Dr. Amanda L Miller",
    "country_code": "US"
  }
}
'

$headers = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"
$headers.Add("Host", "api.shipengine.com")
$headers.Add("API-Key", "__YOUR_API_KEY_HERE__")
$headers.Add("Content-Type", "application/json")

$body = "{`n  `"text`": `"I need to send a package to my friend Amanda Millers house at 525 Winchester Blvd in San Jose (thats california, obviously). The zip code there is 95128.`",`n  `"address`": {`n    `"name`": `"Dr. Amanda L Miller`",`n    `"country_code`": `"US`"`n  }`n}`n"

$response = Invoke-RestMethod 'https://api.shipengine.com/v1/addresses/recognize' -Method 'PUT' -Headers $headers -Body $body
$response | ConvertTo-Json

var myHeaders = new Headers();
myHeaders.append("Host", "api.shipengine.com");
myHeaders.append("API-Key", "__YOUR_API_KEY_HERE__");
myHeaders.append("Content-Type", "application/json");

var raw = JSON.stringify({"text":"I need to send a package to my friend Amanda Millers house at 525 Winchester Blvd in San Jose (thats california, obviously). The zip code there is 95128.","address":{"name":"Dr. Amanda L Miller","country_code":"US"}});

var requestOptions = {
  method: 'PUT',
  headers: myHeaders,
  body: raw,
  redirect: 'follow'
};

fetch("https://api.shipengine.com/v1/addresses/recognize", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

var request = require('request');
var options = {
  'method': 'PUT',
  'url': 'https://api.shipengine.com/v1/addresses/recognize',
  'headers': {
    'Host': 'api.shipengine.com',
    'API-Key': '__YOUR_API_KEY_HERE__',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({"text":"I need to send a package to my friend Amanda Millers house at 525 Winchester Blvd in San Jose (thats california, obviously). The zip code there is 95128.","address":{"name":"Dr. Amanda L Miller","country_code":"US"}})

};
request(options, function (error, response) { 
  if (error) throw new Error(error);
  console.log(response.body);
});

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.shipengine.com/v1/addresses/recognize",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS =>"{\n  \"text\": \"I need to send a package to my friend Amanda Millers house at 525 Winchester Blvd in San Jose (thats california, obviously). The zip code there is 95128.\",\n  \"address\": {\n    \"name\": \"Dr. Amanda L Miller\",\n    \"country_code\": \"US\"\n  }\n}\n",
  CURLOPT_HTTPHEADER => array(
    "Host: api.shipengine.com",
    "API-Key: __YOUR_API_KEY_HERE__",
    "Content-Type: application/json"
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

import requests

url = "https://api.shipengine.com/v1/addresses/recognize"

payload = "{\n  \"text\": \"I need to send a package to my friend Amanda Millers house at 525 Winchester Blvd in San Jose (thats california, obviously). The zip code there is 95128.\",\n  \"address\": {\n    \"name\": \"Dr. Amanda L Miller\",\n    \"country_code\": \"US\"\n  }\n}\n"
headers = {
  'Host': 'api.shipengine.com',
  'API-Key': '__YOUR_API_KEY_HERE__',
  'Content-Type': 'application/json'
}

response = requests.request("PUT", url, headers=headers, data = payload)

print(response.text.encode('utf8'))

require "uri"
require "net/http"

url = URI("https://api.shipengine.com/v1/addresses/recognize")

https = Net::HTTP.new(url.host, url.port);
https.use_ssl = true

request = Net::HTTP::Put.new(url)
request["Host"] = "api.shipengine.com"
request["API-Key"] = "__YOUR_API_KEY_HERE__"
request["Content-Type"] = "application/json"
request.body = "{\n  \"text\": \"I need to send a package to my friend Amanda Millers house at 525 Winchester Blvd in San Jose (thats california, obviously). The zip code there is 95128.\",\n  \"address\": {\n    \"name\": \"Dr. Amanda L Miller\",\n    \"country_code\": \"US\"\n  }\n}\n"

response = https.request(request)
puts response.read_body

var client = new RestClient("https://api.shipengine.com/v1/addresses/recognize");
client.Timeout = -1;
var request = new RestRequest(Method.PUT);
request.AddHeader("Host", "api.shipengine.com");
request.AddHeader("API-Key", "__YOUR_API_KEY_HERE__");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"text\": \"I need to send a package to my friend Amanda Millers house at 525 Winchester Blvd in San Jose (thats california, obviously). The zip code there is 95128.\",\n  \"address\": {\n    \"name\": \"Dr. Amanda L Miller\",\n    \"country_code\": \"US\"\n  }\n}\n",  ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n  \"text\": \"I need to send a package to my friend Amanda Millers house at 525 Winchester Blvd in San Jose (thats california, obviously). The zip code there is 95128.\",\n  \"address\": {\n    \"name\": \"Dr. Amanda L Miller\",\n    \"country_code\": \"US\"\n  }\n}\n");
Request request = new Request.Builder()
  .url("https://api.shipengine.com/v1/addresses/recognize")
  .method("PUT", body)
  .addHeader("Host", "api.shipengine.com")
  .addHeader("API-Key", "__YOUR_API_KEY_HERE__")
  .addHeader("Content-Type", "application/json")
  .build();
Response response = client.newCall(request).execute();

package main

import (
  "fmt"
  "strings"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://api.shipengine.com/v1/addresses/recognize"
  method := "PUT"

  payload := strings.NewReader("{\n  \"text\": \"I need to send a package to my friend Amanda Millers house at 525 Winchester Blvd in San Jose (thats california, obviously). The zip code there is 95128.\",\n  \"address\": {\n    \"name\": \"Dr. Amanda L Miller\",\n    \"country_code\": \"US\"\n  }\n}\n")

  client := &http.Client {
  }
  req, err := http.NewRequest(method, url, payload)

  if err != nil {
    fmt.Println(err)
  }
  req.Header.Add("Host", "api.shipengine.com")
  req.Header.Add("API-Key", "__YOUR_API_KEY_HERE__")
  req.Header.Add("Content-Type", "application/json")

  res, err := client.Do(req)
  defer res.Body.Close()
  body, err := ioutil.ReadAll(res.Body)

  fmt.Println(string(body))
}

#import <Foundation/Foundation.h>

dispatch_semaphore_t sema = dispatch_semaphore_create(0);

NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://api.shipengine.com/v1/addresses/recognize"]
  cachePolicy:NSURLRequestUseProtocolCachePolicy
  timeoutInterval:10.0];
NSDictionary *headers = @{
  @"Host": @"api.shipengine.com",
  @"API-Key": @"__YOUR_API_KEY_HERE__",
  @"Content-Type": @"application/json"
};

[request setAllHTTPHeaderFields:headers];
NSData *postData = [[NSData alloc] initWithData:[@"{\n  \"text\": \"I need to send a package to my friend Amanda Millers house at 525 Winchester Blvd in San Jose (thats california, obviously). The zip code there is 95128.\",\n  \"address\": {\n    \"name\": \"Dr. Amanda L Miller\",\n    \"country_code\": \"US\"\n  }\n}\n" dataUsingEncoding:NSUTF8StringEncoding]];
[request setHTTPBody:postData];

[request setHTTPMethod:@"PUT"];

NSURLSession *session = [NSURLSession sharedSession];
NSURLSessionDataTask *dataTask = [session dataTaskWithRequest:request
completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) {
  if (error) {
    NSLog(@"%@", error);
  } else {
    NSHTTPURLResponse *httpResponse = (NSHTTPURLResponse *) response;
    NSError *parseError = nil;
    NSDictionary *responseDictionary = [NSJSONSerialization JSONObjectWithData:data options:0 error:&parseError];
    NSLog(@"%@",responseDictionary);
    dispatch_semaphore_signal(sema);
  }
}];
[dataTask resume];
dispatch_semaphore_wait(sema, DISPATCH_TIME_FOREVER);

import Foundation

var semaphore = DispatchSemaphore (value: 0)

let parameters = "{\n  \"text\": \"I need to send a package to my friend Amanda Millers house at 525 Winchester Blvd in San Jose (thats california, obviously). The zip code there is 95128.\",\n  \"address\": {\n    \"name\": \"Dr. Amanda L Miller\",\n    \"country_code\": \"US\"\n  }\n}\n"
let postData = parameters.data(using: .utf8)

var request = URLRequest(url: URL(string: "https://api.shipengine.com/v1/addresses/recognize")!,timeoutInterval: Double.infinity)
request.addValue("api.shipengine.com", forHTTPHeaderField: "Host")
request.addValue("__YOUR_API_KEY_HERE__", forHTTPHeaderField: "API-Key")
request.addValue("application/json", forHTTPHeaderField: "Content-Type")

request.httpMethod = "PUT"
request.httpBody = postData

let task = URLSession.shared.dataTask(with: request) { data, response, error in 
  guard let data = data else {
    print(String(describing: error))
    return
  }
  print(String(data: data, encoding: .utf8)!)
  semaphore.signal()
}

task.resume()
semaphore.wait()

Entity Types

The address recognition API is currently designed to recognize the following types of entities:

Entity Type	Recognized Attributes
address	direction: enumerated string ("from" or "to") name: string company_name: string phone: string address_line1: string address_line2: string address_line3: string city_locality: string state_province: string postal_code: string country_code: string address_residential_indicator: enumerated string ("yes", "no", or "unknown")
address_line	line: number(usually 1, 2 or 3) value: string (ex: "525 Winchester Blvd")
city_locality	value: string
country	name: string value: string
number	type: enumerated string ("cardial", "ordinal", "or "percentage") value: number
person	value: string
phone_number	value: string
postal_code	value: string
residential_indicator	value: enumerated string ("yes", "no", or "unknown")
state_province	name: string (ex: "Texas", "Quebec", "New South Wales") value: string (ex: "TX", "QC", "NSW") country: string (ex: "US", "CA", "AU")