Geospatial

Generates spatial geometry as WKT text: points, lines, polygons and their multi-part forms.

Use it for a spatial column with realistic coordinates, such as a delivery drop-off, a sensor position, a service area or a territory outline. The coordinates are generated, so a geometry does not correspond to a real address or boundary. For a real place and its outline, use Location. For a real street address and its point, use Address.

Two independent settings control the output. geometryType sets the kind of geometry on each row, such as a single point or a polygon. The effective area sets where the geometry is placed, such as anywhere in the world or inside one city.

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	Example value	Description
coordinateX	-111.8	The point's X ordinate, as a number. Map it to a Double or Float column. Point only.
coordinateY	33.4	The point's Y ordinate, as a number. Point only.
value	POINT(-111.8 33.4)	The geometry as well-known text. Map it to a Geometry or Geography column. See Geometry or Geography.

coordinateX and coordinateY are for a destination with numeric columns rather than a spatial one. Map them instead of value, or as well as it. All three contain the same point.

The two ordinates apply to geometryType: "Point" only. Every other geometry type has more than one coordinate, so mapping either ordinate with another geometryType is rejected.

Properties

Property	Type	Default	Description
boundingLocation	BoundingLocation?	none	Limits geometry to real places. See Generating inside a real place. Cannot be combined with boundingPolygon, radius or withinCountries.
boundingPolygon	string?	none	Limits geometry to an area given as a WKT POLYGON or MULTIPOLYGON. The minX, minY, maxX and maxY rectangle is then ignored. No geometry is generated inside an interior ring. Cannot be combined with boundingLocation or radius. 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).
boundingPolygonWeights	integer[]?	equal weights	The relative weight of each polygon in a MULTIPOLYGON boundingPolygon, which sets how rows are distributed across them. Every weight must be greater than 0. See Weighting the distribution across polygons.
bufferDistance	number	0	Extends boundingPolygon outward by this distance before it is used, measured on the earth's surface. A negative value shrinks it inward, and a value that shrinks any polygon to nothing is rejected. 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.
geometryType	GeometryType	required	The kind of geometry to generate, such as Point or Polygon.
map	object	required	Maps sub-fields to destination columns. For value, the dataType sets the column type. See Geometry or Geography and Building a Request.
maxInteriorRings	integer	0	The largest number of holes in a polygon. See Rings and holes. Polygon and MultiPolygon only.
maxVertices	integer	depends on geometryType	The largest number of vertices in a geometry. See Vertices.
maxX	number	180	Eastern edge of the rectangle, in longitude, from -180 to 180.
maxY	number	90	Northern edge of the rectangle, in latitude, from -90 to 90.
minInteriorRings	integer	0	The smallest number of holes in a polygon. See Rings and holes. Polygon and MultiPolygon only.
minVertices	integer	depends on geometryType	The smallest number of vertices in a geometry. See Vertices.
minX	number	-180	Western edge of the rectangle, in longitude, from -180 to 180.
minY	number	-90	Southern edge of the rectangle, in latitude, from -90 to 90.
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 each coordinate is rounded to, from 0 to 15, where 0 uses the default. 6 places is about 11 centimeters at the equator.
radius	number	0	Limits geometry to a circle of this radius around 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 or boundingLocation.
radiusUnitOfMeasure	UnitOfMeasure	"Meter"	The unit of radius.
seed	integer	random	Per-field seed, overriding the request's own seed for this field only.
spreadBy	"Coordinates" / "Area"	"Coordinates"	Whether points are spread evenly by longitude and latitude, or evenly by ground area. See Spreading by ground area.
unique	boolean	false	Whether every generated value must differ from the others. Coordinates are generated from a continuous area, so duplicates are rare, but a small area at a low precision has few distinct values. There is no fixed limit, so a request that runs out of distinct values is rejected during generation.
withinCountries	boolean	false	Limits geometry to land within a country's border. See Land only.

UnitOfMeasure

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

Geometry or Geography

The dataType in the field's map sets the column type in the generated schema. There is no separate setting for it.

"map": { "value": { "column": "pickup", "dataType": "Geography" } }

"map": { "value": { "column": "pickup", "dataType": "Geometry" } }

The WKT text is the same for both, so the choice affects only the column definition. value can also be mapped to a text column such as VarChar, which contains the WKT as text.

The effective area

Every geometry is generated inside an effective area, which is set in one of four ways. A MULTIPOLYGON in boundingPolygon, or several places in boundingLocation, gives an area made of separate parts, and each row is generated inside one of them.

Property	Area
boundingLocation	Real places, such as a city, a county or a state.
centerX, centerY and radius	A circle, such as 5 kilometers around a depot.
boundingPolygon	A polygon given as WKT.
minX, minY, maxX and maxY	A rectangle of longitude and latitude.

None of them is required. With none set, the rectangle covers the whole world, so geometry is generated anywhere on the globe, including the oceans.

withinCountries limits whichever area is in effect to the land within country borders. It is a limit on the area rather than a fifth way of setting it. See Land only.

boundingLocation, radius and boundingPolygon cannot be combined, so at most one of them is set. The rectangle is used when none of the three is set.

How the effective area is set. The rectangle is used when none of the other three is set.

Land only

The rectangle, the circle and a WKT polygon include sea as well as land, so a request covering the whole world puts most of its points in the ocean.

withinCountries limits the area in effect to the parts of it within a country's border:

{
  "type": "Geospatial",
  "geometryType": "Point",
  "withinCountries": true,
  "map": { "value": { "column": "location", "dataType": "Geometry" } }
}

location
POINT(-86.006956 75.517964)
POINT(148.876336 -34.126546)
POINT(146.426394 -23.583426)
POINT(31.810902 -16.954737)
POINT(-73.984084 -13.459034)

With no other area set, the area is the whole world, so the points are anywhere on land. Both limits apply when withinCountries is combined with another area:

Combined with	Result
nothing	Anywhere on land.
minX, minY, maxX and maxY	On land, inside the rectangle.
boundingPolygon	On land, inside the polygon.
centerX, centerY and radius	On land, inside the circle.

{
  "type": "Geospatial",
  "geometryType": "Point",
  "withinCountries": true,
  "minX": -10,
  "maxX": 20,
  "minY": 36,
  "maxY": 60,
  "map": { "value": { "column": "location", "dataType": "Geometry" } }
}

location
POINT(5.372276 46.75837)
POINT(6.97079 44.851698)
POINT(-8.246455 41.77253)
POINT(16.823515 44.827571)
POINT(7.355197 47.666089)

Points are distributed in proportion to each country's land area inside the area in effect, so the land is covered evenly rather than split equally between countries. A country with a small land area inside the area can have no points when the row count is low.

withinCountries cannot be combined with boundingLocation, which already limits geometry to real places.

Spreading by ground area

By default, points are spread evenly by longitude and latitude. A degree of longitude covers less ground further from the equator, so over a large area the points are denser toward the poles. At 60 degrees of latitude, a degree of longitude covers half the ground it covers at the equator, so the same area of ground has twice as many points. Over a city or a small region the difference is negligible. Over a continent or the whole world it is significant.

With spreadBy set to "Area", points are spread evenly by ground area, so every square kilometer has the same chance of a point:

{
  "type": "Geospatial",
  "geometryType": "Point",
  "spreadBy": "Area",
  "map": { "value": { "column": "location", "dataType": "Geometry" } }
}

location
POINT(-70.750182 -76.891033)
POINT(55.205413 -2.565806)
POINT(-84.807885 -58.247974)
POINT(25.756173 23.448067)
POINT(-153.862313 -51.329987)

Across the whole world, about a third of the points are beyond 60 degrees north or south by default, because a third of the range of latitudes is. With "Area", about 13% are, which is the proportion of the earth's surface beyond 60 degrees.

"Area" applies to every way of setting the area: the rectangle, the circle, a WKT polygon, withinCountries and boundingLocation. It changes only the position of points within each place. The proportion of rows in each place is unchanged, whether it is set by weights or by each country's land area. It also applies to the points a line or polygon is built from.

GeometryType

geometryType is required, and sets the kind of geometry on every row.

Value	Produces
Point	One coordinate.
LineString	A line through several coordinates in order.
Polygon	A closed outline, optionally with holes in it.
MultiPoint	Several separate points in one value.
MultiLineString	Several separate lines in one value.
MultiPolygon	Several separate outlines in one value, which never overlap.
GeometryCollection	A combination of points, lines and outlines in one value.

The seven geometry types at the same scale. Dots are points, connected dots are lines, and closed outlines are polygons.

Properties by geometry type

Every property applies to every geometry type, except these:

Property	Geometry types
maxInteriorRings, minInteriorRings	MultiPolygon, Polygon
maxVertices, minVertices	Every type except Point

Vertices

A vertex is one coordinate in a geometry. minVertices and maxVertices set the number of vertices in each geometry: the number of points in a LineString or MultiPoint, and the number in each ring of a Polygon or MultiPolygon. Each row has its own number from the range, so a range of 4 to 8 produces a mix of simpler and more detailed geometry.

Point ignores both, because a point always has one coordinate.

Without them, each geometry type uses its own default range:

geometryType	Default range	Smallest accepted minVertices
LineString, MultiLineString	2 to 5	2
MultiPoint	3 to 6	1
Polygon, MultiPolygon	4 to 8	3
GeometryCollection	3 to 6	1

A ring requires at least three vertices to enclose an area.

Rings and holes

A polygon is made of rings. A ring is a closed line, where the last coordinate is the same as the first.

Every polygon has one exterior ring, which is its outer edge. A polygon can also have interior rings, also called holes. The area inside a hole is not part of the polygon. Examples are a park with a private property inside it, and a building footprint with a courtyard.

One polygon with two holes in it. The shaded area is the polygon. The holes are not part of it.

By default, polygons have no holes. minInteriorRings and maxInteriorRings set the number of holes, and each row has its own number from the range, so a range of 1 to 3 gives a mix.

{
  "type": "Geospatial",
  "geometryType": "Polygon",
  "minInteriorRings": 1,
  "maxInteriorRings": 3,
  "map": { "value": { "column": "parcel", "dataType": "Geometry" } }
}

parcel
POLYGON((-18.403807 -1.552885, -29.664115 3.593172, ..., -18.403807 -1.552885), (-29.131662 -5.39372, ..., -29.131662 -5.39372))
POLYGON((6.587462 88.987269, -16.312564 89.174856, ..., 6.587462 88.987269), (-2.761502 86.086744, ..., -2.761502 86.086744), (-7.041563 86.375061, ..., -7.041563 86.375061))
POLYGON((47.922674 50.404705, 32.327948 53.08278, ..., 47.922674 50.404705), (36.828742 45.415235, ...), (28.557396 47.730185, ...), (29.830709 43.633621, ...))

The coordinates are shortened above with .... The three polygons have one, two and three holes.

Every hole is fully inside its polygon, and holes never touch each other, so every value is a valid polygon.

Only Polygon and MultiPolygon can have holes, and the hole properties are rejected for any other geometry type. In a MultiPolygon, the number of holes applies to each polygon separately.

Weighting the distribution across polygons

A MULTIPOLYGON in boundingPolygon contains several separate polygons. Without weights, each polygon has an equal share of the rows, whatever its size. boundingPolygonWeights sets the distribution of rows across the polygons instead.

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": "Geospatial",
  "geometryType": "Point",
  "boundingPolygon": "MULTIPOLYGON(((-74.3 40.5, -73.7 40.5, -73.7 40.9, -74.3 40.9, -74.3 40.5)), ((-87.9 41.6, -87.5 41.6, -87.5 42.0, -87.9 42.0, -87.9 41.6)))",
  "boundingPolygonWeights": [3, 1],
  "seed": 2,
  "map": { "value": { "column": "pickup", "dataType": "Geometry" } }
}

pickup
POINT(-87.738335 41.666399)
POINT(-87.856398 41.722672)
POINT(-87.721781 41.689993)
POINT(-73.84078 40.511497)
POINT(-73.993987 40.652838)
POINT(-73.878147 40.594138)
POINT(-74.246599 40.53306)
POINT(-74.102053 40.792527)

About three quarters of the rows are in the first polygon, around New York, and one quarter in the second, around Chicago. The number of weights must equal the number of polygons, and weights are only accepted when boundingPolygon is a MULTIPOLYGON.

Generating inside a real place

boundingLocation limits geometry to real places, such as a city or a state, instead of a rectangle or a WKT polygon. Every geometry is inside the place's real boundary, so points for Los Angeles are inside the Los Angeles city limits.

{
  "type": "Geospatial",
  "geometryType": "Point",
  "boundingLocation": { "country": "us", "state": "ca", "city": "Los Angeles" },
  "seed": 7,
  "map": { "value": { "column": "customer_location", "dataType": "Geometry" } }
}

The thirteen points in the table below, on the boundary of Los Angeles.

Sample output, the points shown above:

customer_location
POINT(-118.363801 34.009231)
POINT(-118.328716 33.992125)
POINT(-118.41951 34.164636)
POINT(-118.449756 34.324819)
POINT(-118.400556 34.187408)
POINT(-118.193267 34.127653)
POINT(-118.507451 34.294424)
POINT(-118.498606 34.104014)
POINT(-118.599775 34.273259)
POINT(-118.61653 34.265217)
POINT(-118.533704 34.042717)
POINT(-118.420967 33.952879)
POINT(-118.511826 34.069498)

The place filter

boundingLocation has these properties.

Property	Type	Default	Description
country	string?	none	Two-letter country code, such as us. Required for a city, county, state or postal code that does not set its own country, and it must then be a country listed by GET /v1/location/countries. On its own, it can be any country listed by GET /v1/location/world-countries. Cannot be combined with countries.
city	string?	none	City name, such as Los Angeles.
state / region	string?	none	State or territory code, such as ca. See GET /v1/location/regions for the codes.
county / subRegion	string?	none	County name, such as Orange, without the word "County". See GET /v1/location/subregions for the names.
zip / postalCode	string?	none	Postal code, such as 92602. See Postal codes.
cities	CityWeight[]	none	Several cities, each with a weight. See Weighted places.
counties / subRegions	CountyWeight[]	none	Several counties, each with a weight. Synonyms.
states / regions	StateWeight[]	none	Several states, each with a weight. Synonyms.
zips / postalCodes	ZipWeight[]	none	Several postal codes, each with a weight. Synonyms. See Postal codes.
countries	CountryWeight[]	none	Several whole countries, each with a weight. See Whole countries.
overseasTerritories	boolean	false	Whether a whole country includes its regions outside its main landmass. See Overseas territories.

Some properties are listed as a pair, such as state / region or counties / subRegions. These are synonyms, two names for the same property. Setting both names of a pair is rejected.

Place names must match exactly, including accents. See Matching place names.

Overseas territories

Some countries have regions outside their main landmass, such as an overseas department, region, territory or dependency. overseasTerritories sets whether a whole country includes them, and defaults to false.

With false, geometry for a whole country is generated on its main landmass only. With true, it can also be generated in the country's overseas regions.

{
  "type": "Geospatial",
  "geometryType": "Point",
  "boundingLocation": { "country": "fr", "overseasTerritories": true },
  "map": { "value": { "column": "point", "dataType": "Geometry" } }
}

point
POINT(5.482419 43.885494)
POINT(1.580726 48.382042)
POINT(-52.971026 3.383884)
POINT(3.730355 47.634634)
POINT(-1.679853 47.981216)

The third point is in French Guiana.

overseasTerritories applies only to an entry with a country and nothing more specific. A region, sub-region, city or postal code is not affected, so a filter for an overseas region generates geometry in that region.

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.

Different kinds of place

A filter can include different kinds of place together, such as a county and a city, or states, postal codes and whole countries. Every place in the filter adds to the area, and each row is generated inside one of them.

{
  "type": "Geospatial",
  "geometryType": "Point",
  "boundingLocation": {
    "country": "us",
    "counties": [{ "county": "Orange", "state": "ca" }],
    "cities": [{ "city": "Los Angeles", "state": "ca", "weight": 2 }]
  },
  "seed": 4,
  "map": { "value": { "column": "customer_location", "dataType": "Geometry" } }
}

The fifteen points in the table below, on the boundaries of the City of Los Angeles and Orange County. The city has twice the weight, and ten of the fifteen points are in it.

Sample output, the points shown above:

customer_location
POINT(-118.550142 34.186102)
POINT(-118.300601 34.10757)
POINT(-118.259957 33.953334)
POINT(-118.246781 33.934986)
POINT(-118.523017 34.307272)
POINT(-117.859314 33.644653)
POINT(-118.403158 34.02688)
POINT(-118.475365 34.32824)
POINT(-118.439484 34.267505)
POINT(-117.738598 33.50397)
POINT(-118.537248 34.1184)
POINT(-117.616445 33.599868)
POINT(-117.916758 33.854758)
POINT(-118.402986 34.316961)
POINT(-117.828508 33.837273)

The weights apply across all the places in the filter. In the request above, the city has a weight of 2 and the county the default weight of 1, so about two thirds of the rows are in Los Angeles and one third in Orange County.

Places can overlap. A filter can include a state and a city in that state. A point in the city is the same whether it was generated for the city or for the state. The effect is on the distribution, because the city then has a larger share of the rows than it would from the state alone.

The singular and plural properties at the same level cannot be combined. city with cities is rejected, and so is state with states.

Qualifiers

Two properties limit the other places in the filter rather than adding a place of their own.

state is a qualifier when a city or a county is also set. It identifies which of several places with the same name is meant. Many states have a Springfield, so a filter for city: "Springfield" alone is rejected because it matches more than one place, while city: "Springfield" with state: "il" matches one. Set state with a city or county whenever the name is used in more than one state.

{
  "boundingLocation": { "country": "us", "city": "Springfield", "state": "il" }
}

That filter generates geometry in Springfield, Illinois only, and not anywhere else in Illinois. To include the whole state as well, add it to the states list, which is never a qualifier:

{
  "boundingLocation": {
    "country": "us",
    "city": "Springfield",
    "states": [{ "state": "il" }]
  }
}

country is the same. With other places in the filter, it sets the country for those places. Only when no other place is set is it the whole country. Use the countries list to include a whole country with other places.

Weighted places

The plural properties cities, counties, states and countries each contain several places.

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": "Geospatial",
  "geometryType": "Point",
  "boundingLocation": {
    "country": "us",
    "cities": [
      { "city": "Los Angeles", "state": "ca", "weight": 2 },
      { "city": "San Diego", "state": "ca" },
      { "city": "Fresno", "state": "ca", "weight": 0.5 }
    ]
  },
  "map": { "value": { "column": "customer_location", "dataType": "Geometry" } }
}

customer_location
POINT(-118.469828 34.168931)
POINT(-118.553806 34.092537)
POINT(-117.068548 32.980526)
POINT(-118.382466 34.040052)
POINT(-118.430335 33.975591)

The weights are 2, 1 and 0.5, which total 3.5. About 57% of rows are in Los Angeles, 29% in San Diego and 14% in Fresno. Each row is selected separately, so the proportions are approximate.

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

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

{
  "boundingLocation": {
    "country": "us",
    "state": "ca",
    "cities": [{ "city": "Los Angeles" }, { "city": "San Diego" }]
  }
}

Both cities are in California. An entry that sets its own state uses that state instead. See Qualifiers for when state is a qualifier and when it is a place.

Postal codes

A postal code is a kind of place. Set zip or postalCode for one:

{
  "type": "Geospatial",
  "geometryType": "Point",
  "boundingLocation": { "country": "us", "zip": "92602" },
  "map": { "value": { "column": "delivery_point", "dataType": "Geometry" } }
}

delivery_point
POINT(-117.749634 33.738236)
POINT(-117.750724 33.762805)
POINT(-117.721565 33.717718)
POINT(-117.675268 33.691422)
POINT(-117.691074 33.71074)

Use zips or postalCodes for several, with weights in the same way as the other lists:

{
  "type": "Geospatial",
  "geometryType": "Point",
  "boundingLocation": {
    "country": "us",
    "zips": [
      { "zip": "92602", "weight": 3 },
      { "zip": "92618" },
      { "zip": "90045" }
    ]
  },
  "map": { "value": { "column": "delivery_point", "dataType": "Geometry" } }
}

delivery_point
POINT(-117.707411 33.668869)
POINT(-117.755086 33.757024)
POINT(-117.72697 33.732882)
POINT(-117.729714 33.725575)
POINT(-117.686182 33.701587)

About three fifths of the rows are in 92602, and one fifth in each of the others. Each entry can set its own country, as in the other lists.

A postal code identifies one area on its own, so it has no state qualifier. Postal areas do not follow the boundaries of the other levels: a postal code can cross two cities, and a city can contain many postal codes. Each place in the filter is a separate area, so a filter can include a postal code and a city together.

More than one country

Every entry in a cities, counties, states or zips list can set its own country. An entry with no country uses the filter's country. A filter with a place and no country is rejected, because there is no default country. See Setting the country when several are listed.

One field can include places in more than one country:

{
  "type": "Geospatial",
  "geometryType": "Point",
  "boundingLocation": {
    "states": [
      { "country": "us", "state": "ny", "weight": 2 },
      { "country": "au", "state": "qld", "weight": 1 }
    ]
  },
  "map": { "value": { "column": "customer_location", "dataType": "Geometry" } }
}

customer_location
POINT(144.393949 -16.201763)
POINT(-78.693236 42.218023)
POINT(-73.918511 44.216187)
POINT(141.022168 -20.795797)
POINT(-74.73649 43.643156)

About two thirds of the rows are in New York and one third in Queensland. See GET /v1/location/countries for the country codes, and GET /v1/location/regions for the region codes in each country.

For a country with place names in more than one script, a city or county filter can be written in either script. For Japan, "city": "札幌" and "city": "Sapporo" match the same place. Japanese prefecture codes are numeric, 01 to 47, in both scripts. This field generates geometry rather than names, so it has no equivalent of Location.japaneseScript.

Whole countries

With country and no city, county, state or postal code, geometry is generated anywhere inside the country's national boundary.

{
  "type": "Geospatial",
  "geometryType": "Point",
  "boundingLocation": { "country": "fr" },
  "map": { "value": { "column": "shipment_origin", "dataType": "Geometry" } }
}

shipment_origin
POINT(0.45852 49.767645)
POINT(1.301245 42.977896)
POINT(4.380545 43.680104)
POINT(1.273214 47.357149)
POINT(6.942397 45.370748)

Every point is in mainland France, because overseasTerritories defaults to false. See Overseas territories.

A whole country can be any country listed by GET /v1/location/world-countries, which includes many more countries than the city, county and state filters accept. A city, county or state entry must be in a country listed by GET /v1/location/countries. A country code that matches no country is rejected when the request runs.

countries includes several whole countries, with weights as in the other lists:

{
  "boundingLocation": {
    "countries": [
      { "country": "us", "weight": 2 },
      { "country": "fr", "weight": 1 }
    ]
  }
}

countries can be combined with the other levels, for example the whole of Australia with a higher weight on Sydney:

{
  "boundingLocation": {
    "countries": [{ "country": "au" }],
    "cities": [{ "city": "Sydney", "state": "nsw", "country": "au", "weight": 3 }]
  }
}

Three quarters of the rows are in Sydney, and one quarter anywhere in Australia, including Sydney.

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 point anywhere on land

withinCountries limits the default whole-world rectangle to land within country borders.

{
  "type": "Geospatial",
  "geometryType": "Point",
  "withinCountries": true,
  "map": { "value": { "column": "location", "dataType": "Geometry" } }
}

Sample output:

location
POINT(-42.565084 -20.664282)
POINT(16.8117 -25.768212)
POINT(-108.86857 38.414855)
POINT(-61.213894 -19.536071)
POINT(-48.769834 78.410259)

A point on land inside a rectangle

Both limits apply, so the points are on land in western Europe.

{
  "type": "Geospatial",
  "geometryType": "Point",
  "withinCountries": true,
  "minX": -10,
  "maxX": 20,
  "minY": 36,
  "maxY": 60,
  "map": { "value": { "column": "location", "dataType": "Geometry" } }
}

Sample output:

location
POINT(10.835778 53.28956)
POINT(0.771935 45.565372)
POINT(12.183939 56.830097)
POINT(10.291091 50.695296)
POINT(15.621357 50.652579)

A point anywhere on Earth

With no area set, the rectangle covers the whole world.

{
  "type": "Geospatial",
  "geometryType": "Point",
  "map": { "value": { "column": "location", "dataType": "Geometry" } }
}

Sample output:

location
POINT(-53.392789 47.807937)
POINT(-44.732296 -37.697917)
POINT(142.673955 21.234868)
POINT(-131.067069 -23.438379)
POINT(-126.272467 -15.431719)

A point inside a rectangle

A rectangle limits the area without a polygon. This one covers the New York City area.

{
  "type": "Geospatial",
  "geometryType": "Point",
  "minX": -74.3,
  "maxX": -73.7,
  "minY": 40.5,
  "maxY": 40.9,
  "map": { "value": { "column": "location", "dataType": "Geometry" } }
}

Sample output:

location
POINT(-74.21922 40.542199)
POINT(-73.71903 40.677475)
POINT(-74.029067 40.645654)
POINT(-74.287757 40.582525)
POINT(-73.968083 40.849547)

A point within a radius of a fixed location

For locations around a known site, such as deliveries around a depot.

{
  "type": "Geospatial",
  "geometryType": "Point",
  "centerX": -0.1278,
  "centerY": 51.5074,
  "radius": 5,
  "radiusUnitOfMeasure": "Kilometer",
  "map": { "value": { "column": "drop_off", "dataType": "Geometry" } }
}

Sample output:

drop_off
POINT(-0.1599 51.507278)
POINT(-0.112779 51.509563)
POINT(-0.150508 51.470439)
POINT(-0.165502 51.537493)
POINT(-0.189614 51.494235)

A point inside a WKT polygon

The polygon is given as WKT. No point is generated inside its interior ring.

{
  "type": "Geospatial",
  "geometryType": "Point",
  "boundingPolygon": "POLYGON((-0.14 51.50, -0.11 51.50, -0.11 51.52, -0.14 51.52, -0.14 51.50), (-0.131 51.508, -0.126 51.508, -0.126 51.512, -0.131 51.512, -0.131 51.508))",
  "map": { "value": { "column": "location", "dataType": "Geometry" } }
}

Sample output:

location
POINT(-0.130445 51.506452)
POINT(-0.128027 51.513332)
POINT(-0.125854 51.519984)
POINT(-0.137917 51.505703)
POINT(-0.11049 51.500169)

A line with a set number of vertices

minVertices and maxVertices apply to lines as well as polygons. Each row has its own number of vertices from the range.

{
  "type": "Geospatial",
  "geometryType": "LineString",
  "minVertices": 4,
  "maxVertices": 8,
  "map": { "value": { "column": "route", "dataType": "Geometry" } }
}

Sample output:

route
LINESTRING(82.563177 -52.022913, 12.727652 -87.875242, 1.973677 -52.775503, -67.017669 63.625287)
LINESTRING(125.948377 53.078459, -174.913335 50.287799, 52.140976 29.162793, 87.615863 47.734264, 4.067069 1.626427, 13.391506 5.059078, 133.35672 63.285023)
LINESTRING(-33.286663 -69.972114, 86.715544 43.824707, 129.064694 74.799884, -107.304558 16.424084, 81.81215 -15.620536)

A polygon with holes in it

A service area in Los Angeles with one or two areas excluded from it.

{
  "type": "Geospatial",
  "geometryType": "Polygon",
  "minVertices": 6,
  "maxVertices": 10,
  "minInteriorRings": 1,
  "maxInteriorRings": 2,
  "boundingLocation": { "country": "us", "state": "ca", "city": "Los Angeles" },
  "map": { "value": { "column": "service_area", "dataType": "Geometry" } }
}

Sample output:

service_area
POLYGON((-118.396557 34.180766, -118.382926 34.200855, ..., -118.396557 34.180766), (-118.407049 34.165604, ..., -118.407049 34.165604))
POLYGON((-118.505191 34.283919, -118.505726 34.302818, ..., -118.505191 34.283919), (-118.508974 34.271573, ...), (-118.523494 34.271258, ...))
POLYGON((-118.240859 34.086199, -118.265821 34.083589, ..., -118.240859 34.086199), (-118.269768 34.05861, ..., -118.269768 34.05861))

The coordinates are shortened above with ....

A Geography column

The dataType in the map sets the column type. The WKT is the same for Geometry and Geography.

{
  "type": "Geospatial",
  "geometryType": "Point",
  "boundingLocation": { "country": "gb" },
  "map": { "value": { "column": "sighting", "dataType": "Geography" } }
}

Sample output:

sighting
POINT(-4.356978 51.86364)
POINT(-7.02399 57.83195)
POINT(-0.846486 51.095583)
POINT(-2.255023 53.565497)
POINT(-1.773298 53.5672)

Points in a county and a city

This includes all of Orange County and the City of Los Angeles, which is not in Orange County. The city has twice the weight.

{
  "type": "Geospatial",
  "geometryType": "Point",
  "boundingLocation": {
    "country": "us",
    "counties": [{ "county": "Orange", "state": "ca" }],
    "cities": [{ "city": "Los Angeles", "state": "ca", "weight": 2 }]
  },
  "map": { "value": { "column": "customer_location", "dataType": "Geometry" } }
}

Sample output:

customer_location
POINT(-118.509291 34.223694)
POINT(-118.497972 34.076984)
POINT(-118.289118 33.721856)
POINT(-118.279565 34.015945)
POINT(-118.439774 34.241734)

Setting the country when several are listed

A city, county, state or postal code with no country 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 for the other entries. A countries entry also adds the whole country as an area. This filter generates geometry in East Ayrshire only:

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

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

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. This filter generates geometry in Queensland and East Ayrshire only:

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

Adding "countries": [{ "country": "au" }, { "country": "gb" }] to it adds the whole of Australia and the whole of the United Kingdom as two more areas.

A whole country with two weighted cities

Whole countries can be combined with cities. Most rows are in the two cities, and the rest anywhere in Australia.

{
  "type": "Geospatial",
  "geometryType": "Point",
  "boundingLocation": {
    "countries": [{ "country": "au" }],
    "cities": [
      { "city": "Sydney", "state": "nsw", "country": "au", "weight": 4 },
      { "city": "Melbourne", "state": "vic", "country": "au", "weight": 2 }
    ]
  },
  "map": { "value": { "column": "customer_location", "dataType": "Geometry" } }
}

Sample output:

customer_location
POINT(130.706717 -25.236191)
POINT(151.211215 -33.863038)
POINT(151.217502 -33.867945)
POINT(122.404658 -17.497482)
POINT(151.21369 -33.869176)

Every level at once

Cities, a county, states, postal codes and whole countries in one field. Each row is in one of the nine places, selected by weight.

{
  "type": "Geospatial",
  "geometryType": "Point",
  "boundingLocation": {
    "cities": [
      { "city": "Los Angeles", "state": "ca", "country": "us", "weight": 4 },
      { "city": "Sydney", "state": "nsw", "country": "au" }
    ],
    "counties": [{ "county": "Orange", "state": "ca", "country": "us" }],
    "states": [
      { "state": "ny", "country": "us" },
      { "state": "vic", "country": "au" }
    ],
    "zips": [
      { "zip": "92602", "country": "us" },
      { "zip": "90045", "country": "us", "weight": 0.5 }
    ],
    "countries": [{ "country": "fr" }, { "country": "jp" }]
  },
  "map": { "value": { "column": "customer_location", "dataType": "Geometry" } }
}

Sample output:

customer_location
POINT(-117.724114 33.720011)
POINT(142.124767 43.975045)
POINT(-118.268722 34.125044)
POINT(-118.405406 33.944684)
POINT(-118.357903 34.11779)

Null rows

{
  "type": "Geospatial",
  "geometryType": "Point",
  "nullPercentageMin": 20,
  "nullPercentageMax": 20,
  "seed": 2,
  "map": { "value": { "column": "last_known_position", "dataType": "Geometry" } }
}

Sample output:

last_known_position
POINT(-34.501466 -60.120239)
POINT(-140.758332 -34.797527)
POINT(-19.603196 -49.503032)
POINT(-169.652307 -88.638986)
POINT(-42.445806 -39.706419)

Points as separate X and Y columns

For a destination with no spatial column, map the two ordinates instead of value.

{
  "type": "Geospatial",
  "geometryType": "Point",
  "precision": 5,
  "boundingLocation": { "country": "us", "state": "az", "city": "Phoenix" },
  "map": {
    "coordinateX": { "column": "longitude", "dataType": "Double" },
    "coordinateY": { "column": "latitude", "dataType": "Double" }
  }
}

Sample output:

longitude	latitude
-112.10213	33.3913
-112.24194	33.41408
-112.0476	33.31342
-112.22891	33.4156
-112.02695	33.41601

Map value as well for both forms. The geometry and the two numbers contain the same point.