Location

Generates a real place, selected at random: a city, a county, a state, a postal area or a country, with its real name and its real boundary.

Use it for place data that matches the real world. Every city exists, is in the county and state it is reported in, and has its real boundary. A row with Irvine, Orange and CA is a city that is in Orange County, California.

For generated coordinates rather than a real place, use Geospatial. For a real street address, use Address.

Boundaries from Location: Orange County, California, and six of its cities. A county row has the outer boundary, and a city row has one of the inner ones.

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

Each row is one place, and the mapped sub-fields set which details of it are written. At least one must be mapped.

Sub-field	Example value	Description
city	Irvine	The city name on its own.
cityName	Irvine city	The city's full official name.
country	us	The two-letter country code.
countryName	United States of America	The full country name.
county / subRegion	Orange	The county name on its own, without the word "County".
countyName / subRegionName	Orange County	The county's full official name, which is not always the plain name plus "County". Louisiana has parishes and Alaska has boroughs, so this can be Orleans Parish or Anchorage Municipality.
location	POLYGON((...))	The place's real boundary as WKT. Map it to a Geometry column. It is much larger than any other sub-field, which limits the number of rows a request can produce. See Boundaries.
name	Irvine city	The full name of the place at the level of the row. Not available for a postal code, which has no name.
state / region	CA	The state or territory code.
stateName / regionName	California	The full state name.
zip	92602	The postal code.

Several sub-fields are listed as a pair, such as state / region. These are synonyms, two names for the same value. Mapping both writes the same value to two columns.

Properties

Property	Type	Default	Description
boundingLocation	BoundingLocation?	none	The places rows are selected from. It has the same structure as on Geospatial. See Weighted places.
boundingPolygon	string?	none	Limits rows to places whose boundary overlaps this WKT POLYGON or MULTIPOLYGON. The polygon 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). See Filtering by polygon or radius. Cannot be combined with radius.
bufferDistance	number	0	Extends boundingPolygon outward by this distance before it is used, so places just outside it are included. 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.
fidelity	string	"Full"	The level of detail in a location boundary: Full, High, Medium, Low or Box. Ignored unless location is mapped. See Boundary detail.
japaneseScript	"Romaji" / "Kanji"	"Romaji"	The script Japanese place names are written in. Only valid for jp. See Japanese script.
map	object	required	Maps 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.
radius	number	0	Limits rows to places within this distance of centerX and centerY. Only applies above 0, and must not be negative. It cannot be more than half the earth's circumference. Cannot be combined with boundingPolygon.
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 row must be a different place. Limited by the number of places that match the filters, so a filter for one city has one place. A request for more unique rows than the field can produce is rejected before any data is generated, stating how many are available.

Combining properties

boundingLocation can be combined with boundingPolygon or with radius. boundingLocation sets the places rows are selected from, and boundingPolygon or radius limits them to the places inside a polygon or a circle, such as cities in California within 50 kilometers of a point.

These combinations are rejected:

• boundingPolygon with radius.
• bufferDistance without boundingPolygon.
• The singular and plural property for the same level in boundingLocation, such as state with states.
• A postal code with a city, county or state. See Postal codes.

UnitOfMeasure

bufferDistance and radius accept these units: Millimeter, Centimeter, Meter, Kilometer, Inch, Foot, Yard and Mile.

The level of each row

A row is one place, which can be a city, a county, a state, a postal area or a country. The level is set by the mapped sub-fields, not by the filters. Each row is at the most detailed level that is mapped:

• With city or cityName mapped, every row is a city.
• With a county sub-field mapped and no city sub-field, every row is a county.
• With only state sub-fields mapped, every row is a state.
• With none of these mapped, every row is a city.

A city is in a county, which is in a state, which is in a country, so a city row can include all of those levels.

Places are inside one another, so a city row can include its county, state and country. A postal code is not part of this nesting and is used on its own.

With only country or countryName mapped, every row is a country, and its boundary is the national boundary. This level includes every country listed by GET /v1/location/world-countries, not only those listed by GET /v1/location/countries:

{
  "type": "Location",
  "map": {
    "country": { "column": "code", "dataType": "VarChar" },
    "countryName": { "column": "country", "dataType": "VarChar" },
    "location": { "column": "outline", "dataType": "Geometry" }
  }
}

code	country	outline
jo	Jordan	POLYGON ((35.611758 32.6819, 35.635995 32.679143, ...))
vi	United States Virgin Islands	MULTIPOLYGON (((-64.585194 17.748969, -64.670522 17.717231, ...)))
do	Dominican Republic	MULTIPOLYGON (((-71.541168 17.554633, -71.541371 17.576158, ...)))
mp	Northern Mariana Islands	MULTIPOLYGON (((145.290538 14.181383, 145.282074 14.161038, ...)))
qa	Qatar	POLYGON ((50.807872 24.746649, 50.826671 24.748684, ...))

The boundaries are shortened above with ....

countryName is available at every level, so a city row can also include the full country name.

Countries at each level

Below the country level, the filter must include a country, with boundingLocation.country or boundingLocation.countries. There is no default country, so a request with none is rejected. The countries accepted depend on the level:

Level	Countries accepted
country / countryName	Any country listed by GET /v1/location/world-countries. With no country in the filter, rows are from all of them.
city, state	Any country listed by GET /v1/location/countries.
county / subRegion	A country whose subRegion property is true in that list.
zip	A country whose postal property is true in that list.

A country with no data for the mapped level is rejected, rather than returning no rows.

This request maps city, so every row is a city. It also maps the county and the full name of each city:

{
  "type": "Location",
  "boundingLocation": { "country": "us", "state": "ca" },
  "map": {
    "city": { "column": "city", "dataType": "VarChar" },
    "county": { "column": "county", "dataType": "VarChar" },
    "name": { "column": "place_name", "dataType": "VarChar" },
    "location": { "column": "boundary", "dataType": "Geometry" }
  }
}

city	county	place_name	boundary
Thornton	San Joaquin	Thornton CDP	POLYGON ((-121.444296 38.246082, -121.438458 38.246143, ...))
Morongo Valley	San Bernardino	Morongo Valley CDP	POLYGON ((-116.622301 34.070255, -116.620032 34.070989, ...))
Monmouth	Fresno	Monmouth CDP	POLYGON ((-119.746024 36.569131, -119.734075 36.569119, ...))
Ripon	San Joaquin	Ripon city	POLYGON ((-121.156352 37.729697, -121.151187 37.729699, ...))
Day Valley	Santa Cruz	Day Valley CDP	POLYGON ((-121.903385 37.022622, -121.900627 37.025806, ...))

state: "ca" in the filter does not make the rows states. It limits the rows to cities in California.

A filter cannot be for a more detailed level than the mapped sub-fields. A county filter with only state sub-fields mapped is rejected, because more than one state could contain a matching county. A city filter with no city sub-field mapped is rejected for the same reason.

Boundaries

Warning

Check whether location is needed, and how large the boundaries are, before mapping it. One boundary can be larger than a thousand rows of every other sub-field, and boundaries set the number of rows a request can produce. Every place-listing endpoint returns outlineCharacters for each place, so check the places first and multiply by the number of rows: regions, sub-regions, cities, postal codes and world countries.

Every sub-field except location is a name or a code. location is the place's boundary, and its size varies greatly between places, because a coastline with thousands of islands includes every island.

Boundaries count toward the data limit of a request, so mapping location greatly reduces the number of rows one request can produce. The size depends more on which places are selected than on the number of rows, which is why the place-listing endpoints return the size of each place.

To reduce the size of a request with boundaries:

1. Leave location unmapped. Every other sub-field is a name or a code, as small as any other column.
2. Use a lower fidelity. Medium is a fraction of the size and keeps every feature of the boundary visible at map scale.
3. Map a less detailed level. A city boundary is a fraction of the size of the region that contains it.

Boundary detail

A boundary has more detail than most uses require. A boundary on a map, or a test of whether a point is inside a region, needs only a small fraction of the points. fidelity sets how much detail is kept, and a lower setting produces a smaller boundary.

Setting	Keeps
Full	The complete boundary, with no detail removed.
High	Detail larger than about 0.1% of the place's size.
Medium	Detail larger than about 0.5% of the place's size.
Low	Detail larger than about 2% of the place's size.
Box	The bounding rectangle only.

The detail removed is measured against the size of each place, so a small town and a whole province lose the same proportion of their detail. The default is Full. The place-listing endpoints return the size of each place at Full, and a lower setting is smaller.

The setting does not change which places are selected, only their boundaries, so the same request with the same seed returns the same places at every setting. Every boundary is a valid polygon, and no ring crosses itself. On the largest boundaries, islands smaller than the setting's detail can be removed.

The size reduction depends on the place. A coastline with thousands of islands keeps most of them at every setting, because removing an island changes the boundary itself. Box is the only setting with the same size for every place.

Start with Medium. It is a fraction of the size and keeps every feature of the boundary visible at map scale.

Matching place names

A place name in a filter must match exactly, including accents. Names are spelled as in their own country, so Montréal, Cañon City and Cwmbrân include their accents, and Montreal does not match Montréal.

Matching ignores case, so montréal, Montréal and MONTRÉAL all match. Region and postal codes are matched the same way, so qc and QC are both accepted. Accents, hyphens, apostrophes and spacing must match.

Copy the name from these endpoints rather than typing it:

Endpoint	Lists
GET /v1/location/regions	Regions within a country.
GET /v1/location/subregions	Sub-regions within a region.
GET /v1/location/cities	Cities within a region.
GET /v1/location/postalcodes	Postal areas within a country.

A name that matches no place is rejected, and the error identifies the filter:

No location matched country 'us', state 'co', city 'Canon City'.

A name that matches more than one place includes all of them. A city filter for Springfield in the United States, with no state, includes the Springfields in every state that has one. Set state with a city or county to limit it to one.

Weighted places

country, state, county and city each limit the rows to one place. The plural properties, countries, states, counties and cities, each contain several places, with a weight for each.

Each entry is one place, with an optional weight relative to the other entries. Weights are relative, not percentages, so 2 and 1 give the same distribution as 20 and 10: the first place is selected twice as often as the second. An entry with no weight has a weight of 1.

{
  "type": "Location",
  "boundingLocation": {
    "country": "us",
    "states": [
      { "state": "ca", "weight": 2 },
      { "state": "ny" },
      { "state": "tx", "weight": 0.5 }
    ]
  },
  "map": {
    "city": { "column": "city", "dataType": "VarChar" },
    "state": { "column": "state", "dataType": "VarChar" }
  }
}

city	state
Romoland	CA
Grayson	CA
Green Valley	CA
La Grange	CA
Patchogue	NY

The weights are 2, 1 and 0.5, which total 3.5. About 57% of rows are cities in California, 29% in New York and 14% in Texas. Each row is selected separately, so the proportions are approximate.

The distribution of rows set by the three weights above. Each state's share is its weight divided by the total of 3.5.

A list with one entry is the same as the singular property.

The singular and plural property at the same level cannot be combined. state with states is rejected.

A filter can include different levels together, such as states and counties. Each row is from one of the places in the filter, selected by weight:

{
  "boundingLocation": {
    "country": "us",
    "states": [
      { "state": "ny", "weight": 2 }
    ],
    "counties": [
      { "county": "Orange", "state": "ca" }
    ]
  }
}

This filter includes all of New York State and Orange County, California, with New York selected twice as often. The weights apply across all the places in the filter.

A countries entry adds every place at the mapped level in that country, such as every city when city is mapped. The singular country is different. With other places in the filter, it only sets their country, and it is the whole country only when no other place is set.

Places can overlap. A filter can include California and a county in California, and the county then has a larger share of the rows than it would from California alone. With unique set, a place in both is counted once in the number of distinct places available.

A single state applies to every counties entry that does not set its own state:

{
  "boundingLocation": {
    "country": "us",
    "state": "ca",
    "counties": [
      { "county": "Orange" },
      { "county": "Placer" }
    ]
  }
}

Both counties are in California. An entry that sets its own state uses that state instead. County names are used in many states, so a county with no state can match several counties.

A countries list can be combined with the other levels, for example anywhere in Australia, or in California:

{
  "boundingLocation": {
    "countries": [
      { "country": "au" }
    ],
    "states": [
      { "state": "ca", "country": "us" }
    ]
  }
}

Each entry in a states or counties list can also set its own country. See More than one country.

A postal code cannot be combined with a state, county or city. See Postal codes.

More than one country

Every entry in a countries, states, counties, cities or zips list can set its own country.

An entry with no country, and every singular property such as county, uses the filter's country. That works when the filter has one country, set by country or by a countries list with one entry. The two are different. country only sets the country, so this filter returns places in East Ayrshire only:

{
  "boundingLocation": {
    "country": "gb",
    "state": "SCT",
    "county": "East Ayrshire"
  }
}

With "countries": [{ "country": "gb" }] in place of "country": "gb", the same filter returns places in East Ayrshire and anywhere in the United Kingdom, each with a weight of 1.

A filter with no country is rejected, because there is no default country. The exception is a field that maps only country and countryName, which can leave out boundingLocation to select from every country. See Countries at each level.

When the filter has several countries, an entry with no country is rejected, because the country cannot be determined. Set the country on each entry instead, using the plural list for that level, since the singular properties have no country of their own:

{
  "boundingLocation": {
    "states": [{ "state": "qld", "country": "au" }],
    "counties": [{ "county": "East Ayrshire", "state": "SCT", "country": "gb" }]
  }
}

This filter includes Queensland and East Ayrshire. Adding "countries": [{ "country": "au" }, { "country": "gb" }] to it adds the whole of Australia and the whole of the United Kingdom as two more places.

The same rules apply to Geospatial, which has the same boundingLocation.

One field can include places in more than one country:

{
  "type": "Location",
  "boundingLocation": {
    "states": [
      { "country": "us", "state": "ny", "weight": 2 },
      { "country": "au", "state": "qld", "weight": 1.5 }
    ]
  },
  "map": {
    "city": { "column": "city", "dataType": "VarChar" },
    "state": { "column": "state", "dataType": "VarChar" },
    "country": { "column": "country", "dataType": "VarChar" }
  }
}

city	state	country
Westmoreland	NY	us
Postmans Ridge	QLD	au
Jacksonville	NY	us
Schuylerville	NY	us
Baroondah	QLD	au

Region codes are different lengths in different countries, and the same code can be used in more than one country, so map country with state when the filter includes several countries.

See GET /v1/location/countries for the countries a region, sub-region, city or postal code entry can be in, GET /v1/location/world-countries for the countries accepted on their own, GET /v1/location/regions for the region codes in each country, and GET /v1/location/subregions for the sub-region names in each region.

Overseas territories

Some countries have regions outside their main landmass, such as an overseas department, region, territory or dependency.

overseasTerritories sets whether a country includes these regions. It defaults to false, so a filter for a country returns places on its main landmass only.

{
  "boundingLocation": { "country": "fr" }
}

Set it to true to include the overseas regions:

{
  "boundingLocation": { "country": "fr", "overseasTerritories": true }
}

With country set to fr and state mapped, the default returns only mainland regions, such as ARA, BRE and IDF. With overseasTerritories set to true, the rows also include overseas regions such as GF, GP and MQ.

overseasTerritories is set on boundingLocation, not on each entry, so it applies to the whole field.

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 this filter returns places in Réunion with the default setting:

{
  "boundingLocation": { "country": "fr", "region": "RE" }
}

GET /v1/location/regions has an overseas property on every region, which identifies the regions outside the main landmass. For a country with no overseas regions, the setting has no effect.

Japanese script

Japanese place names have two spellings, and japaneseScript sets which one is written.

japaneseScript	city	name / cityName	stateName / regionName
"Romaji" (default)	Sapporo	Sapporo-shi	Hokkaido
"Kanji"	札幌	札幌市	北海道

The romanized spelling is modified Hepburn without long vowel marks, which is the usual spelling of Japanese place names in English, such as Tokyo rather than Tōkyō. city has no administrative suffix, and name includes it, in the same way as for every other country.

{
  "type": "Location",
  "boundingLocation": { "country": "jp" },
  "japaneseScript": "Kanji",
  "map": {
    "state": { "column": "prefecture_code", "dataType": "VarChar" },
    "stateName": { "column": "prefecture", "dataType": "VarChar" },
    "city": { "column": "city", "dataType": "VarChar" },
    "name": { "column": "place_name", "dataType": "VarChar" }
  }
}

prefecture_code	prefecture	city	place_name
02	青森県	平内	平内町
06	山形県	天童	天童市
24	三重県	木曽岬	木曽岬町
07	福島県	金山	金山町
33	岡山県	和気	和気町

Filtering in either script

japaneseScript changes only the output. A city filter is accepted in either script, whatever the setting. This field has filters in both scripts in one list:

{
  "type": "Location",
  "boundingLocation": {
    "country": "jp",
    "cities": [{ "city": "札幌" }, { "city": "Yokohama" }, { "city": "那覇" }]
  },
  "japaneseScript": "Kanji",
  "map": {
    "city": { "column": "city", "dataType": "VarChar" },
    "location": { "column": "boundary", "dataType": "Geometry" }
  }
}

city	boundary
札幌	POLYGON ((141.235334721 42.824141946, ...))
横浜	MULTIPOLYGON (((139.632843554 35.323949081, ...)))
那覇	MULTIPOLYGON (((127.643832685 26.177417901, ...)))
横浜	POLYGON ((141.255230999 40.969360973, ...))
横浜	MULTIPOLYGON (((139.632843554 35.323949081, ...)))

There are two places named Yokohama, the city in Kanagawa and a town in Aomori, so the Yokohama filter includes both. The fourth row is the town in Aomori. Set state on the entry to limit it to one.

Prefecture codes are the same in both scripts. Japan's are the JIS numbers, 01 to 47, so a state filter is "state": "01" in both scripts. Call GET /v1/location/regions with country=jp for every code with both of its names.

Where it applies

japaneseScript set to any value except "Romaji" is rejected for a field with any country except jp. The Name field's script setting has the same rule. "Hiragana" is rejected for every Location field, because places have no Hiragana spelling.

county / subRegion and zip are not available for jp. Its subRegion and postal properties in GET /v1/location/countries are both false.

Postal codes

A postal code identifies one area on its own, so it is used without a city, county or state.

{
  "type": "Location",
  "boundingLocation": { "country": "us" },
  "map": {
    "zip": { "column": "postal_code", "dataType": "VarChar" }
  }
}

postal_code
70661
45406
70775
14428

Postal areas do not follow city, county or state boundaries. A postal code can cross two cities, and a city can contain many postal codes. A postal area is not linked to a city, county or state, so a postal code filter or sub-field with a city, county or state filter or sub-field is rejected.

A country filter is accepted, because it only sets the country of the postal codes:

{
  "type": "Location",
  "boundingLocation": { "country": "au" },
  "map": {
    "zip": { "column": "postcode", "dataType": "VarChar" },
    "country": { "column": "country", "dataType": "VarChar" }
  }
}

postcode	country
2231	au
3351	au
4659	au
5330	au
5400	au

The country must have a postal property of true in GET /v1/location/countries.

For a city and a postal code from the same street address, use Address.

Filtering by polygon or radius

boundingPolygon and radius limit rows to real places in an area of the map. Both apply to the real boundaries of the places.

boundingPolygon limits rows to places whose boundary overlaps a WKT polygon. bufferDistance extends the polygon outward first, so places just outside it are included.

{
  "type": "Location",
  "boundingLocation": { "country": "us" },
  "boundingPolygon": "POLYGON((-118.7 33.7, -117.6 33.7, -117.6 34.4, -118.7 34.4, -118.7 33.7))",
  "bufferDistance": 2,
  "bufferUnitOfMeasure": "Kilometer",
  "map": {
    "city": { "column": "city", "dataType": "VarChar" }
  }
}

city
Palos Verdes Estates
Pasadena
Baldwin Park
South San Jose Hills
East Pasadena

centerX, centerY and radius limit rows to places within a distance of a point:

{
  "type": "Location",
  "boundingLocation": { "country": "us" },
  "centerX": -118.2437,
  "centerY": 34.0522,
  "radius": 25,
  "radiusUnitOfMeasure": "Kilometer",
  "map": {
    "city": { "column": "city", "dataType": "VarChar" }
  }
}

city
Rosemead
Hawthorne
Whittier
Commerce
South Whittier

Both are filters. They limit which places are selected, and each place keeps its real boundary.

Examples

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

A country and its boundary

With only country sub-fields mapped, every row is a country, from every country in the world.

{
  "type": "Location",
  "map": {
    "country": { "column": "code", "dataType": "VarChar" },
    "countryName": { "column": "country", "dataType": "VarChar" },
    "location": { "column": "outline", "dataType": "Geometry" }
  }
}

code	country	outline
ss	South Sudan	POLYGON ((35.920835 4.619332, 35.781222 4.619922, ...))
hu	Hungary	POLYGON ((22.877601 47.946739, 22.861167 47.933819, ...))
am	Armenia	MULTIPOLYGON (((45.0394 41.23118, 45.029323 41.210096, ...)))
li	Liechtenstein	POLYGON ((9.521155 47.262801, 9.547096 47.243035, ...))
um	United States Minor Outlying Islands	MULTIPOLYGON (((-176.476877 0.197455, -176.47529 0.193101, ...)))

A simplified state boundary

fidelity reduces the detail of each boundary. At Medium, a state boundary is usually from a twentieth to a half of its Full size, depending on the country, and keeps every feature visible at map scale.

{
  "type": "Location",
  "fidelity": "Medium",
  "boundingLocation": { "country": "us" },
  "map": {
    "state": { "column": "state", "dataType": "VarChar" },
    "location": { "column": "outline", "dataType": "Geometry" }
  }
}

state	outline
MA	MULTIPOLYGON (((-70.23714 41.28512, -70.06257 41.30873, ...)))
VA	MULTIPOLYGON (((-75.7405 37.80124, -75.73872 37.80904, ...)))
ND	POLYGON ((-104.04544 45.94531, -104.04874 48.99988, ...))
UT	POLYGON ((-114.0506 37.0004, -114.04148 41.99387, ...))
VT	POLYGON ((-73.43774 44.04501, -73.39058 44.19089, ...))

A bounding box instead of a boundary

Box produces the rectangle around each place, which has five points for every place. Use it for a geometry column where the exact boundary is not needed.

{
  "type": "Location",
  "fidelity": "Box",
  "boundingLocation": { "country": "us", "state": "ca" },
  "map": {
    "city": { "column": "city", "dataType": "VarChar" },
    "location": { "column": "extent", "dataType": "Geometry" }
  }
}

city	extent
Long Beach	POLYGON ((-118.24897 33.73292, -118.24897 33.88544, -118.06317 33.88544, -118.06317 33.73292, -118.24897 33.73292))
Bayview	POLYGON ((-122.32867 38.00064, -122.32867 38.01162, -122.31333 38.01162, -122.31333 38.00064, -122.32867 38.00064))
Litchfield	POLYGON ((-120.40422 40.37346, -120.40422 40.40816, -120.34548 40.40816, -120.34548 40.37346, -120.40422 40.37346))

Postal codes from one country

{
  "type": "Location",
  "boundingLocation": { "country": "au" },
  "map": {
    "zip": { "column": "postcode", "dataType": "VarChar" },
    "country": { "column": "country", "dataType": "VarChar" }
  }
}

postcode	country
5125	au
6743	au
3432	au
5091	au
3941	au

A city with every level above it

With city mapped, every row is a city, and the levels above it are from the same row.

{
  "type": "Location",
  "boundingLocation": { "country": "us", "state": "ca" },
  "map": {
    "city": { "column": "city", "dataType": "VarChar" },
    "county": { "column": "county", "dataType": "VarChar" },
    "stateName": { "column": "state_name", "dataType": "VarChar" },
    "countryName": { "column": "country", "dataType": "VarChar" }
  }
}

city	county	state_name	country
Sierra City	Sierra	California	United States of America
Robinson Mill	Butte	California	United States of America
East Niles	Kern	California	United States of America
Saratoga	Santa Clara	California	United States of America
Commerce	Los Angeles	California	United States of America

One city

A filter for one city returns the same city on every row.

{
  "type": "Location",
  "boundingLocation": { "country": "us", "city": "Los Angeles", "state": "ca" },
  "map": {
    "city": { "column": "city", "dataType": "VarChar" },
    "name": { "column": "place_name", "dataType": "VarChar" },
    "location": { "column": "boundary", "dataType": "Geometry" }
  }
}

city	place_name	boundary
Los Angeles	Los Angeles city	POLYGON ((-118.668153 34.17675, -118.66814 34.191331, ...))
Los Angeles	Los Angeles city	POLYGON ((-118.668153 34.17675, -118.66814 34.191331, ...))
Los Angeles	Los Angeles city	POLYGON ((-118.668153 34.17675, -118.66814 34.191331, ...))

Cities weighted across several states

{
  "type": "Location",
  "boundingLocation": {
    "country": "us",
    "states": [
      { "state": "ca", "weight": 2 },
      { "state": "ny" },
      { "state": "tx", "weight": 0.5 }
    ]
  },
  "map": {
    "city": { "column": "city", "dataType": "VarChar" },
    "state": { "column": "state", "dataType": "VarChar" }
  }
}

city	state
Tivoli	NY
Lyncourt	NY
Novato	CA
French Camp	CA
Salinas	CA

About 57% of rows are in California, 29% in New York and 14% in Texas.

A state and a county together

This includes all of New York State and Orange County, California.

{
  "type": "Location",
  "boundingLocation": {
    "country": "us",
    "states": [{ "state": "ny", "weight": 2 }],
    "counties": [{ "county": "Orange", "state": "ca" }]
  },
  "map": {
    "city": { "column": "city", "dataType": "VarChar" },
    "county": { "column": "county", "dataType": "VarChar" },
    "state": { "column": "state", "dataType": "VarChar" }
  }
}

city	county	state
Anaheim	Orange	CA
Oxbow	Jefferson	NY
Garden Grove	Orange	CA
Sherburne	Chenango	NY
Seneca Falls	Seneca	NY

Two countries in one field

Each entry sets its own country.

{
  "type": "Location",
  "boundingLocation": {
    "states": [
      { "country": "us", "state": "ny", "weight": 2 },
      { "country": "au", "state": "qld" }
    ]
  },
  "map": {
    "city": { "column": "city", "dataType": "VarChar" },
    "state": { "column": "state", "dataType": "VarChar" },
    "country": { "column": "country", "dataType": "VarChar" }
  }
}

city	state	country
Mungabunda	QLD	au
Bedford Hills	NY	us
Scio	NY	us
Wanakah	NY	us
Blantyre	QLD	au

A whole country and one state

A countries entry can be combined with the other levels, so this includes anywhere in Spain, or in California.

{
  "type": "Location",
  "boundingLocation": {
    "countries": [{ "country": "es" }],
    "states": [{ "state": "ca", "country": "us" }]
  },
  "map": {
    "city": { "column": "city", "dataType": "VarChar" },
    "state": { "column": "state", "dataType": "VarChar" },
    "country": { "column": "country", "dataType": "VarChar" }
  }
}

city	state	country
Rubiales	AR	es
Carucedo	CL	es
Campins	CT	es
Trowbridge	CA	us
Azusa	CA	us

The two entries have equal weight, so each has about half the rows, however many places each contains.

A state in one country and a county in another

Each entry sets its own country, so this includes Queensland and East Ayrshire.

{
  "type": "Location",
  "boundingLocation": {
    "states": [{ "state": "qld", "country": "au" }],
    "counties": [{ "county": "East Ayrshire", "state": "SCT", "country": "gb" }]
  },
  "map": {
    "city": { "column": "city", "dataType": "VarChar" },
    "state": { "column": "state", "dataType": "VarChar" },
    "country": { "column": "country", "dataType": "VarChar" }
  }
}

city	state	country
Goorganga Plains	QLD	au
Murrigal	QLD	au
Doongul	QLD	au
Auchinleck	SCT	gb
Darvel	SCT	gb

The two entries have equal weight, so each has about half the rows.

An Australian suburb with its local government area

{
  "type": "Location",
  "boundingLocation": { "country": "au", "state": "nsw" },
  "map": {
    "city": { "column": "suburb", "dataType": "VarChar" },
    "county": { "column": "lga", "dataType": "VarChar" },
    "name": { "column": "place_name", "dataType": "VarChar" },
    "location": { "column": "boundary", "dataType": "Geometry" }
  }
}

suburb	lga	place_name	boundary
Esk	Clarence Valley	Esk (NSW)	POLYGON ((153.376166 -29.239071, 153.3747 -29.241135, ...))
Mount Riverview	Blue Mountains	Mount Riverview	POLYGON ((150.635905 -33.733184, 150.634636 -33.740379, ...))
Widgelli	Griffith	Widgelli	POLYGON ((146.177433 -34.373621, 146.156666 -34.383564, ...))
Balgowlah Heights	Northern Beaches	Balgowlah Heights	POLYGON ((151.271109 -33.804586, 151.271573 -33.804538, ...))
Castle Hill	The Hills	Castle Hill (NSW)	POLYGON ((150.98369 -33.707832, 150.983013 -33.706225, ...))

Japanese cities in kanji

{
  "type": "Location",
  "boundingLocation": { "country": "jp", "state": "13" },
  "japaneseScript": "Kanji",
  "map": {
    "city": { "column": "city", "dataType": "VarChar" },
    "stateName": { "column": "prefecture", "dataType": "VarChar" },
    "location": { "column": "boundary", "dataType": "Geometry" }
  }
}

city	prefecture	boundary
東村山	東京都	POLYGON ((139.448523774 35.749096667, ...))
清瀬	東京都	POLYGON ((139.497226783 35.762816081, ...))
中野	東京都	POLYGON ((139.674629222 35.721499135, ...))
八丈	東京都	MULTIPOLYGON (((139.681051115 33.125121108, ...)))
府中	東京都	POLYGON ((139.520964643 35.651019532, ...))

Japanese cities in romaji

Without japaneseScript, the names are in romaji.

{
  "type": "Location",
  "boundingLocation": { "country": "jp", "state": "13" },
  "map": {
    "city": { "column": "city", "dataType": "VarChar" },
    "stateName": { "column": "prefecture", "dataType": "VarChar" },
    "location": { "column": "boundary", "dataType": "Geometry" }
  }
}

city	prefecture	boundary
Ota	Tokyo	MULTIPOLYGON (((139.80708869 35.531106748, ...)))
Hamura	Tokyo	POLYGON ((139.318965525 35.750759171, ...))
Fussa	Tokyo	POLYGON ((139.313868301 35.747124171, ...))
Hinohara	Tokyo	POLYGON ((139.157247834 35.666593802, ...))
Ogasawara	Tokyo	MULTIPOLYGON (((141.275016355 25.421497883, ...)))

Places inside a polygon

boundingLocation and boundingPolygon can be combined, so this includes cities in California whose boundaries overlap the polygon.

{
  "type": "Location",
  "boundingLocation": { "country": "us", "state": "ca" },
  "boundingPolygon": "POLYGON((-122.6 37.2, -121.7 37.2, -121.7 38.0, -122.6 38.0, -122.6 37.2))",
  "map": {
    "city": { "column": "city", "dataType": "VarChar" },
    "location": { "column": "boundary", "dataType": "Geometry" }
  }
}

city	boundary
Pacheco	POLYGON ((-122.080061 37.976068, -122.079714 37.979982, ...))
Dublin	POLYGON ((-121.987797 37.709318, -121.973833 37.709396, ...))
Contra Costa Centre	POLYGON ((-122.059726 37.924484, -122.060096 37.926462, ...))
San Jose	MULTIPOLYGON (((-121.759124 37.397994, -121.75554 37.399438, ...)))
Redwood City	MULTIPOLYGON (((-122.262284 37.483954, -122.261913 37.48603, ...)))

Places within a distance of a point

{
  "type": "Location",
  "boundingLocation": { "country": "us" },
  "centerX": -118.2437,
  "centerY": 34.0522,
  "radius": 50,
  "radiusUnitOfMeasure": "Kilometer",
  "map": {
    "city": { "column": "city", "dataType": "VarChar" },
    "state": { "column": "state", "dataType": "VarChar" }
  }
}

city	state
Palos Verdes Estates	CA
San Gabriel	CA
Signal Hill	CA
Diamond Bar	CA
San Fernando	CA

Unique places

With unique set, every row is a different place.

{
  "type": "Location",
  "boundingLocation": { "country": "us", "state": "ca" },
  "unique": true,
  "map": {
    "city": { "column": "city", "dataType": "VarChar" },
    "location": { "column": "boundary", "dataType": "Geometry" }
  }
}

city	boundary
Alderpoint	POLYGON ((-123.630963 40.152089, -123.627579 40.160024, ...))
Vineyard	POLYGON ((-121.391444 38.481666, -121.371978 38.481645, ...))
Hilmar-Irwin	POLYGON ((-120.868164 37.418877, -120.831697 37.418604, ...))
Cutler	POLYGON ((-119.304775 36.530436, -119.295727 36.530356, ...))
Montara	POLYGON ((-122.519494 37.537403, -122.516589 37.544939, ...))

Null rows

{
  "type": "Location",
  "boundingLocation": { "country": "us" },
  "nullPercentageMin": 15,
  "nullPercentageMax": 15,
  "seed": 2,
  "map": {
    "city": { "column": "city", "dataType": "VarChar" }
  }
}

city
Potomac
Ernest
Sullivan's Island
Supai
Wallace