Table of Contents

Address

Generates a real street address: a house number, a street, a unit where the address has one, and the city, county, state and postal code of the address. It is one level more detailed than Location, which generates a city, county, state or postal area.

All the parts of an address in a row are from the same real address. The house number exists on that street, the street is in that city, and the point is the position of that address. An address made by combining other field types, such as a Number for the house number, a String for the street and a Location for the city, is usually a combination that does not exist.

Use it for records that include a postal address, such as customers, deliveries, service calls and claims.

Sub-fields: at least one must be mapped. See Sub-fields.

Every JSON block on this page is a single field object, one entry in a table's fields array. See Building a Request for the full request structure.

Sub-fields

Sub-field Produces
addressLine1 House number and street as one line, e.g. 7807 East Golden Lasso Lane.
addressLine2 The unit, where the address has one. Empty otherwise. See addressLine2.
city The city the address is in, e.g. Phoenix.
cityName The city's full official name, e.g. Phoenix city.
coordinateX The X ordinate of that same point on its own, as a number, e.g. -111.604778. Map it to a Double or Float column.
coordinateY The Y ordinate of that same point on its own, as a number, e.g. 33.233986.
country The country code, e.g. us.
countryName The full country name.
county / subRegion The county the address is in, e.g. Maricopa. Synonyms.
countyName / subRegionName The county's full official name, e.g. Maricopa County, which is not always the plain name plus "County". Louisiana has parishes and Alaska has boroughs, so this can read Orleans Parish or Anchorage Municipality. Synonyms.
location The address's own point, as WKT, e.g. POINT(-111.604778 33.233986), rounded to precision. Map it to a Geometry column.
number The house number on its own, e.g. 7807.
state / region The state code, e.g. AZ. Synonyms.
stateName / regionName The full state name, e.g. Arizona. Synonyms.
street The street on its own, e.g. East Golden Lasso Lane.
unit The unit identifier on its own, unformatted.
zip / postalCode The postal code. Synonyms.

addressLine1 contains the same values as number and street. The same applies to addressLine2 and unit.

cityName and countyName are official names, which include the type of place: a city reads Phoenix city or Sun Lakes CDP, and a county reads Maricopa County. Map city or county for the name alone.

Some names are used by more than one place in the same state. Arizona has both a Cottonwood city and a Cottonwood CDP, which are different areas. An address does not identify which of the two it is in, so for these places cityName is the plain name.

location, coordinateX and coordinateY are the same point in different forms. Map location to a spatial column, the two ordinates to numeric columns, or all three.

{
  "type": "Address",
  "boundingLocation": { "country": "us", "state": "az" },
  "map": {
    "addressLine1": { "column": "address_1", "dataType": "VarChar" },
    "addressLine2": { "column": "address_2", "dataType": "VarChar" },
    "city": { "column": "city", "dataType": "VarChar" },
    "state": { "column": "state", "dataType": "VarChar" },
    "zip": { "column": "postal_code", "dataType": "VarChar" }
  }
}

Sample output:

address_1 address_2 city state postal_code
5020 West Peoria Avenue 259 Glendale AZ 85302
17460 West Willow Avenue Surprise AZ 85388
1500 East Cedar Avenue 10 Flagstaff AZ 86004

An address outside any incorporated place has no city, so city is empty for that row. This is common for rural addresses. All other parts of the address are populated.

Properties

Property Type Default Description
addressLine2Style AddressLineTwoStyle "Number" How a mapped addressLine2 writes the unit.
boundingLocation BoundingLocation? none The places addresses are selected from. See Filtering by place.
boundingPolygon string? none Limits addresses to those whose point is inside this WKT POLYGON or MULTIPOLYGON. The shape must be valid: every ring is closed and none crosses itself, and every coordinate is a valid longitude (-180 to 180) and latitude (-90 to 90).
boundingPolygonWeights integer[]? none The relative weight of each polygon in a MULTIPOLYGON boundingPolygon, which sets how rows are distributed across them. See Weighting the distribution across polygons.
bufferDistance number 0 Extends boundingPolygon outward by this distance before it is applied. Requires boundingPolygon.
bufferUnitOfMeasure UnitOfMeasure "Meter" The unit of bufferDistance.
centerX number 0 Longitude of the circle's center, from -180 to 180. Only used when radius is set.
centerY number 0 Latitude of the circle's center, from -90 to 90. Only used when radius is set.
map object required Maps the field's sub-fields to destination columns. See Building a Request.
nullPercentageMax number 0 Upper bound (0-100) of the percentage of rows that should be null. See nullPercentageMin.
nullPercentageMin number 0 Lower bound (0-100) of the percentage of rows that should be null. The rate is fixed once for the whole field from this range, not recalculated per row. Set equal to nullPercentageMax for an exact rate.
precision integer 6 How many decimal places a mapped location, coordinateX or coordinateY is rounded to, from 0 to 15, where 0 uses the default. 6 places is about 11 centimeters at the equator. Lower it for less detail.
radius number 0 Limits addresses to those within this distance of centerX/centerY. Only applies above 0, and must not be negative. It cannot be more than half the Earth's circumference.
radiusUnitOfMeasure UnitOfMeasure "Meter" The unit of radius.
seed integer random Per-field seed, overriding the request's own seed for this field only.
unique boolean false Whether every generated address must differ from the others. Limited by the number of addresses that match the filters. A request for more unique rows than the field can produce is rejected before any data is generated, stating how many are available.

boundingLocation, boundingPolygon and radius can be combined. boundingLocation selects the places addresses come from, and boundingPolygon or radius limits those addresses to the ones inside a shape or a circle. boundingPolygon and radius cannot be used together.

addressLine2

Most addresses have no unit, and for those addressLine2 is empty. For an address with a unit, addressLine2Style sets how the unit is written.

AddressLineTwoStyle

Value Writes
Number 101
Apt Apt 101
Unit Unit 101
Suite Suite 101 
{
  "type": "Address",
  "addressLine2Style": "Apt",
  "boundingLocation": { "country": "us", "city": "Phoenix" },
  "map": {
    "addressLine1": { "column": "address_1", "dataType": "VarChar" },
    "addressLine2": { "column": "address_2", "dataType": "VarChar" }
  }
}
address_1 address_2
5849 West Palm Lane
8400 West Virginia Avenue Apt 1077
3738 East Amelia Avenue
4520 East Cesar Chavez Boulevard Apt 1041

A unit identifier is written in the form the address uses, which can be a number, a letter or a short code. addressLine2Style only sets the text written before it.

Filtering by place

boundingLocation has the same structure as on Location and Geospatial. An Address field matches only places that have addresses, so a place that a Location or Geospatial filter accepts can match nothing here. See Places with addresses.

{
  "type": "Address",
  "boundingLocation": {
    "country": "us",
    "cities": [
      { "city": "Phoenix", "weight": 3 },
      { "city": "Tucson" }
    ]
  },
  "map": {
    "addressLine1": { "column": "address_1", "dataType": "VarChar" },
    "city": { "column": "city", "dataType": "VarChar" }
  }
}
address_1 city
1009 East Marco Polo Road Phoenix
612 North Main Street Phoenix
4080 East Michigan Street Tucson
1515 North 44th Street Phoenix
2209 North 9th Street Phoenix
4915 East Thomas Road Phoenix

Weights are relative, not percentages, so about three quarters of the rows are Phoenix addresses and one quarter are Tucson addresses.

Every place in a filter must have a country, set either by boundingLocation.country or on the entry itself. There is no default country, and a filter with a place but no country is rejected.

With no boundingLocation, addresses are selected from every place that has them.

Places with addresses

Addresses are not available for every part of every country. A filter for a place that has no addresses is not an error, but it matches nothing. These endpoints list the places that have addresses:

Endpoint Lists
GET /v1/address/countries Countries with addresses.
GET /v1/address/regions Regions within a country that have addresses, and the number of addresses in each.
GET /v1/address/subregions Sub-regions within a region that have addresses, and the number of addresses in each.
GET /v1/address/cities Cities within a region that have addresses, and the number of addresses in each.

These endpoints list fewer places than the /v1/location endpoints, which list every place rather than only the places with addresses.

Name matching

A region, sub-region or city name must match exactly, including accents. Cañon City, Española and Bayamón are spelled with their accents, and Canon City does not match Cañon City.

Matching ignores case, and region codes are matched the same way, so nm and NM are both accepted. Accents, hyphens, apostrophes and spacing must match.

{
  "type": "Address",
  "boundingLocation": {
    "country": "us",
    "cities": [
      { "city": "Española", "state": "nm" },
      { "city": "Cañon City", "state": "CO" },
      { "city": "Bayamón", "state": "pr" }
    ]
  },
  "map": {
    "addressLine1": { "column": "address_1", "dataType": "VarChar" },
    "city": { "column": "city", "dataType": "VarChar" },
    "state": { "column": "state", "dataType": "VarChar" }
  }
}
address_1 city state
394 Chinook Drive Cañon City CO
609 Candlewood Drive Cañon City CO
J-3 Calle 16 Bayamón PR
351 Seven Fawns Drive Cañon City CO
1751 State Road 76 Española NM
2A-2 Laurel Bayamón PR

Each city is written with its accents, and the state codes are accepted in lower or upper case. The same filter with Espanola instead of Española is rejected, because no address is in a city spelled Espanola.

Copy the name from GET /v1/address/regions, GET /v1/address/subregions or GET /v1/address/cities rather than typing it.

Postal codes with cities, counties and states

Unlike on Location, a postal-code filter on Address can be used in the same boundingLocation as a city, county or state. Each one adds its own places, so the addresses are from the postal codes in the filter and from the other places in the filter. A postal code does not limit a city or state in the same filter.

{
  "type": "Address",
  "boundingLocation": {
    "country": "us",
    "state": "az",
    "city": "Tucson",
    "zips": [{ "zip": "85003" }, { "zip": "85016" }]
  },
  "map": {
    "addressLine1": { "column": "address_1", "dataType": "VarChar" },
    "city": { "column": "city", "dataType": "VarChar" },
    "zip": { "column": "zip", "dataType": "VarChar" }
  }
}
address_1 city zip
825 West 24th Street Tucson 85713
8842 East Stone Meadow Circle Tucson 85730
8748 East Giachery Place Tucson 85747
17 West Vernon Avenue Phoenix 85003
805 North 4th Avenue Phoenix 85003
1016 North 1st Drive Phoenix 85003

The rows are split between Tucson and the two Phoenix postal codes. On Location, a postal area has no city, county or state, so a postal-code filter there cannot be combined with them.

States with cities and counties

A state set with a city limits the city to that state, which selects the right city when the same name is used in more than one state:

{
  "type": "Address",
  "boundingLocation": { "country": "us", "state": "az", "city": "Phoenix" },
  "map": {
    "addressLine1": { "column": "address_1", "dataType": "VarChar" },
    "city": { "column": "city", "dataType": "VarChar" },
    "state": { "column": "state", "dataType": "VarChar" }
  }
}
address_1 city state
11807 South Tonopah Drive Phoenix AZ
303 East South Mountain Avenue Phoenix AZ
6209 East Juniper Avenue Phoenix AZ
2150 West Alameda Road Phoenix AZ

A filter with both a city and a county is rejected.

Overseas territories

overseasTerritories sets whether a country includes its regions outside its main landmass. It defaults to false, so a country filter returns addresses on the main landmass only.

{
  "type": "Address",
  "boundingLocation": { "country": "us", "overseasTerritories": true },
  "map": {
    "state": { "column": "state", "dataType": "VarChar" }
  }
}

Puerto Rico is an overseas region of the United States. The rows in Puerto Rico out of 20,000:

overseasTerritories Rows Rows in Puerto Rico
false 20,000 0
true 20,000 6

Without overseasTerritories, no row is in Puerto Rico. With it, Puerto Rico's addresses are included with the rest of the country.

It applies only to an entry with a country and nothing more specific. An entry with a region, sub-region, city or postal code is not affected, so a filter for an overseas region returns addresses in that region. See Overseas territories.

{
  "type": "Address",
  "boundingLocation": { "country": "us", "state": "pr" },
  "map": {
    "addressLine1": { "column": "address_1", "dataType": "VarChar" },
    "city": { "column": "city", "dataType": "VarChar" },
    "state": { "column": "state", "dataType": "VarChar" },
    "zip": { "column": "zip", "dataType": "VarChar" }
  }
}
address_1 city state zip
U-4 Calle 18 Bayamón PR 00961
16 Pegaso Carolina PR 00979
706 Baleares San Juan PR 00920
4-JN-12 Vía Fabiana Carolina PR 00983
N-13 Senda de la Posada Bayamón PR 00961
W-139 P Zorrilla San Juan PR 00926

The entry names Puerto Rico as its region, so every row is in Puerto Rico without overseasTerritories.

Filtering by polygon or radius

boundingPolygon limits addresses to those inside a shape, and radius limits them to those within a distance of a point. Either can be combined with boundingLocation. This example returns addresses in Phoenix within two kilometers of a point:

{
  "type": "Address",
  "boundingLocation": { "country": "us", "city": "Phoenix" },
  "centerX": -112.074,
  "centerY": 33.448,
  "radius": 2,
  "radiusUnitOfMeasure": "Kilometer",
  "map": {
    "addressLine1": { "column": "address_1", "dataType": "VarChar" },
    "location": { "column": "point", "dataType": "Geometry" }
  }
}
address_1 point
311 North 1st Avenue POINT(-112.074832 33.45188)
402 West Lincoln Street POINT(-112.081541 33.443237)
355 North Central Avenue POINT(-112.073416 33.452186)

The point is the position of the address itself, not a generated point.

Weighting the distribution across polygons

A MULTIPOLYGON contains several separate polygons. Without weights, every address in any of the polygons is equally likely, so the number of rows from each polygon is proportional to the number of addresses it contains. boundingPolygonWeights sets the distribution of rows across the polygons instead, regardless of how many addresses each one contains.

Give one weight per polygon, in the same order as the polygons in the WKT. Weights are relative, so [3, 1] and [30, 10] give the same distribution: three rows from the first polygon for every row from the second.

{
  "type": "Address",
  "boundingLocation": { "country": "us", "city": "Phoenix" },
  "boundingPolygon": "MULTIPOLYGON(((-112.09 33.44, -112.06 33.44, -112.06 33.46, -112.09 33.46, -112.09 33.44)), ((-112.02 33.49, -111.99 33.49, -111.99 33.51, -112.02 33.51, -112.02 33.49)))",
  "boundingPolygonWeights": [3, 1],
  "map": {
    "addressLine1": { "column": "address_1", "dataType": "VarChar" },
    "location": { "column": "point", "dataType": "Geometry" }
  }
}
address_1 point
4133 North 34th Place POINT(-112.007472 33.4965)
412 East Garfield Street POINT(-112.068447 33.457817)
400 North 2nd Avenue POINT(-112.077083 33.453746)
730 West Portland Street POINT(-112.084227 33.459906)
340 North 5th Avenue POINT(-112.080431 33.452814)
4307 North 34th Street POINT(-112.008362 33.49924)
601 West Fillmore Street POINT(-112.082219 33.454405)
205 West Portland Street POINT(-112.076754 33.459579)

About three quarters of the rows are from the first polygon and one quarter from the second. Within each polygon, every address is equally likely.

The weights apply within each place in boundingLocation. With two weighted cities and two weighted polygons, the rows for each city are distributed across the two polygons in the same proportions.

The number of weights must equal the number of polygons, and every weight must be greater than 0. Weights are rejected without a boundingPolygon, and with a single POLYGON. A polygon that contains no addresses is rejected, and the error gives its position in the WKT.

Examples

Each example below is a single field object, one entry in a table's fields array within a full request. See Building a Request for how it fits into a full DatasetRequest.

A full postal address

{
  "type": "Address",
  "addressLine2Style": "Apt",
  "boundingLocation": { "country": "us", "state": "az" },
  "map": {
    "addressLine1": { "column": "line_1", "dataType": "VarChar" },
    "addressLine2": { "column": "line_2", "dataType": "VarChar" },
    "city": { "column": "city", "dataType": "VarChar" },
    "state": { "column": "state", "dataType": "VarChar" },
    "zip": { "column": "zip", "dataType": "VarChar" },
    "countryName": { "column": "country", "dataType": "VarChar" }
  }
}
line_1 line_2 city state zip country
7713 East Vista Drive Scottsdale AZ 85250 United States of America
1050 North Horne Apt 6 Mesa AZ 85203 United States of America
1770 North Terrace Circle Casa Grande AZ 85122 United States of America

Address parts in separate columns

For a schema with the house number and street in separate columns.

{
  "type": "Address",
  "boundingLocation": { "country": "us", "city": "Tucson" },
  "map": {
    "number": { "column": "house_number", "dataType": "VarChar" },
    "street": { "column": "street", "dataType": "VarChar" },
    "unit": { "column": "unit", "dataType": "VarChar" },
    "city": { "column": "city", "dataType": "VarChar" }
  }
}
house_number street unit city
3701 East Grant Road Tucson
8002 East 17th Place Tucson
2071 West Jim Howard Place Tucson
1051 East Bilby Road Tucson

Addresses with their points

The point is the position of the address in the same row.

{
  "type": "Address",
  "boundingLocation": { "country": "us", "county": "Maricopa", "state": "az" },
  "map": {
    "addressLine1": { "column": "address", "dataType": "VarChar" },
    "city": { "column": "city", "dataType": "VarChar" },
    "location": { "column": "point", "dataType": "Geometry" }
  }
}
address city point
5431 West Townley Avenue Glendale POINT(-112.177085 33.566143)
6544 East University Drive Mesa POINT(-111.6894 33.423899)
42424 North Gavilan Peak Parkway Anthem POINT(-112.136251 33.868917)

The same point is also available as two numbers, for a destination with no spatial column:

{
  "type": "Address",
  "boundingLocation": { "country": "us", "county": "Maricopa", "state": "az" },
  "map": {
    "addressLine1": { "column": "address", "dataType": "VarChar" },
    "coordinateX": { "column": "longitude", "dataType": "Double" },
    "coordinateY": { "column": "latitude", "dataType": "Double" }
  }
}
address longitude latitude
22242 East Cherrywood Drive -111.604778 33.233986
7701 West Saint John Road -112.223673 33.644586
4600 North 24th Street -112.031054 33.504172

Weighted cities

{
  "type": "Address",
  "boundingLocation": {
    "country": "us",
    "cities": [
      { "city": "Phoenix", "state": "az", "weight": 4 },
      { "city": "Mesa", "state": "az", "weight": 2 },
      { "city": "Flagstaff", "state": "az" }
    ]
  },
  "map": {
    "addressLine1": { "column": "address_1", "dataType": "VarChar" },
    "city": { "column": "city", "dataType": "VarChar" }
  }
}
address_1 city
14846 South 5th Avenue Phoenix
1201 East Ponderosa Parkway Flagstaff
4026 East Yawepe Street Phoenix
11449 East Rafael Avenue Mesa
6067 East Dodge Street Mesa
10328 East Mesquite Street Mesa
2738 West Sahuaro Drive Phoenix

The weights total 7, so about four rows in seven are Phoenix addresses, two in seven are Mesa addresses and one in seven is a Flagstaff address. The city of each row is selected separately, so the split is approximate. Over 140 rows:

city Weight Rows
Phoenix 4 83
Mesa 2 40
Flagstaff 1 17

Unique addresses

{
  "type": "Address",
  "unique": true,
  "boundingLocation": { "country": "us", "city": "Flagstaff" },
  "map": { "addressLine1": { "column": "address_1", "dataType": "VarChar" } }
}
address_1
2652 East Route 66
5000 North Mall Way
3361 East Miller Drive
1450 East Castle Hills Drive
1926 North Fourth Street

A request for more unique addresses than match the filters is rejected before any data is generated.

Null rows

{
  "type": "Address",
  "nullPercentageMin": 10,
  "nullPercentageMax": 10,
  "boundingLocation": { "country": "us", "state": "az" },
  "map": {
    "addressLine1": { "column": "address_1", "dataType": "VarChar" },
    "city": { "column": "city", "dataType": "VarChar" }
  }
}
address_1 city
519 East Roger Road Tucson
5817 North Placita Esplendora Catalina Foothills
10352 West Zimmerman Street Marana
360 West 5th Street Benson
3660 South Bonnie Brae Valle
1547 West Eva Street Phoenix
6032 East 28th Street Tucson
6973 North Bowen Boulevard Prescott Valley
2802 A Park Circle Pinetop Country Club

Every mapped column is empty on a null row, so a row never has a city without a street address.