Point Datatype

The Point datatype is very similar to the Location datatype. It represents a location on the Earth as a WGS84 Latitude and Longitude. The location is encoded as a GeoJSON “point”. Example:

{
  "type": "Point",
  "coordinates": [
    -87.653274,
    41.936172
  ]
}
Heads up! Contrary to the normal convention of "latitude, longitude" ordering in the coordinates property, the GeoJSON orders the coordinates as "longitude, latitude" (X coordinate, Y coordinate), as other GIS coordiate systems are encoded. Note that the SoQL within_box and within_circle functions use the more conventional ordering, however.

The following operators can be used on point fields:

Operation Description
IS NULL TRUE for values that are NULL.
IS NOT NULL TRUE for values that are not NULL.

The following table describes the functions that can be used with points.

Function Name Description Availability
case(...) Returns different values based on the evaluation of boolean comparisons 2.1
convex_hull(...) Returns the minimum convex geometry that encloses all of the geometries within a set 2.1
count(...) Returns a count of a given set of records 2.0 and 2.1
distance_in_meters(...) Returns the distance between two Points in meters 2.1
extent(...) Returns a bounding box that encloses a set of geometries 2.1
intersects(...) Allows you to compare two geospatial types to see if they intersect or overlap each other 2.1
num_points(...) Returns the number of vertices in a geospatial data record 2.1
within_box(...) Returns the rows that have geodata within the specified box, defined by latitude, longitude corners 2.0 and 2.1
within_circle(...) Returns the rows that have locations within a specified circle, measured in meters 2.0 and 2.1
within_polygon(...) Returns the rows that have locations within the specified box, defined by latitude, longitude corners 2.1

Just like the Location datatype, you can use thewithin_circle(...) function to look for points within a given range. For example, to get all of the crimes within 500 meters of Chicago City Hall:

https://data.cityofchicago.org/resource/6zsd-86xi.json?$where=within_circle(location, 41.883811, -87.631749, 500)

However, there are also a ton of additional geo query functions that come with the Point datatype. For example, to aggregate that same dataset by ward and return polygons surrounding each cluster, in GeoJSON:

https://data.cityofchicago.org/resource/6zsd-86xi.geojson?$select=ward, count(*), convex_hull(location)&$group=ward

Why are the latitude and longitude backwards?!

Back in school, you were taught that points on the earth were defined as “degrees of latitude and longitude”, right? You probably used them to find locations on the globe, to locate your campsite, or to plot the location of that prime fishing spot or anchorage. So why then are locations in the Point datatype encoded as $longitude, $latitude?

Well, a latitude and longitude pair, usually used on a Mercator projection is actually only one of many many different ways of translating locations on our (semi-)spherical world onto a flat piece of paper (or an LCD monitor). Not only are there dozens of ways of flattening that globe into a plane (called map projections), but there are also thousands of ways of actually mapping coordinates onto those projections.

GeoJSON and Well Known Text are designed to be flexible to work with many different map projections and coordinate projections, and just like the Cartesian coordinates you learned in math class, those coordinates are encoded in “X, Y” order. With the EPSG:4326 coordinate system that we use for our geospatial datatypes, that means that the coordinates are encoded in $longitude, $latitude order.

For fun, check out this excellent XKCD comic to see what your favorite map projection says about you.