Geographic Concepts

This document covers concepts and methods in the Geo API.

The main purpose of the Geo API is to manage polygons on the map and their associated metadata. This includes user-defined Locations, as well as points of interest and auxiliary helper regions, such as Markets.

Before we get into each type of location, there are a few concepts that every object in this API is built upon.

Coordinate System

For the purposes of this API, you can assume everything is in the WGS84 coordinate system. A point in this system is represented by a (longitude, latitude) pair, where longitude is a value between -180 and 180, and latitude is a value between -90 and 90.

This coordinate system presents a few issues when doing some transformations. Most notably, because the system is in degrees and not any sort of measure of distance, performing "meters-based" calculations have a few extra steps, which we provide helper endpoints for.

Geofences

Geometry Example

{
  "type": "Polygon",
  "coordinates": [
    [
      [-74.00866448, 40.7113473],
      [-74.00873422, 40.71124165],
      [-74.00889784, 40.711042],
      [-74.00899171, 40.7108960],
      [-74.00887370, 40.71082689],
      [-74.00816023, 40.7104527],
      [-74.00779008, 40.7108228],
      [-74.00866448, 40.7113473]
    ]
  ]
}

A geofence is simply a 2-D shape on the map of the world. Geofences can be represented by Polygons, which are lists of linear ring sequences that describe the boundaries and holes in a particular shape. For the most part, we will be utilizing simple polygons -- those with no holes and only one linear ring -- such as this one in the sidebar.

A geofence could technically also be a Multipolygon as well, which is a union of disjoint polygons. So for example, if you wanted to geofence the state of Hawaii in one geofence, it would be represented as a Multipolygon.

In the context of this API, Geofences are not resources that can be accessed, but should instead be thought of as a superclass to or interface for many location-contextualized objects in the API. Locations, POIs, Markets, Block Groups, and Postal Codes are all subclasses/implementations of the Geofence class. This provides them with a geometry property that is used to access the Polygon/Multipolygon, as well as a covering property, which provides access to the Geofence's underlying covering (explained below).

An aside: it is good to familiarize oneself with the GeoJSON spec, which is a method of encoding geographical information.