docs-v2/content/flux/v0/stdlib/experimental/geo/_index.md

title	description	menu	weight	cascade
geo package	The `geo` package provides tools for working with geotemporal data, such as filtering and grouping by geographic location.	flux_v0_ref name parent identifier geo experimental experimental/geo	21	flux/v0/tags introduced geotemporal 0.63.0

The geo package provides tools for working with geotemporal data, such as filtering and grouping by geographic location. Import the experimental/geo package:

import "experimental/geo"

Geo schema requirements

The Geo package uses the Go implementation of the S2 Geometry Library. Functions in the geo package require the following:

• a s2_cell_id tag containing an S2 cell ID as a token
• a lat field containing the latitude in decimal degrees (WGS 84)
• a lon field containing the longitude in decimal degrees (WGS 84)

Schema recommendations

• a tag that identifies the data source
• a tag that identifies the point type (for example: start, stop, via)
• a field that identifies the track or route (for example: id, tid)

Examples of geotemporal line protocol

taxi,pt=start,s2_cell_id=89c2594 tip=3.75,dist=14.3,lat=40.744614,lon=-73.979424,tid=1572566401123234345i 1572566401947779410
bike,id=biker-007,pt=via,s2_cell_id=89c25dc lat=40.753944,lon=-73.992035,tid=1572588100i 1572567115

S2 Cell IDs

Use latitude and longitude with the s2.CellID.ToToken endpoint of the S2 Geometry Library to generate s2_cell_id tags. Specify your S2 Cell ID level.

Note: To filter more quickly, use higher S2 Cell ID levels, but know that higher levels increase series cardinality.

Language-specific implementations of the S2 Geometry Library provide methods for generating S2 Cell ID tokens. For example:

• Go: s2.CellID.ToToken()
• Python: s2sphere.CellId.to_token()
• JavaScript: s2.cellid.toToken()

Add S2 Cell IDs to existing geotemporal data

Use geo.shapeData() to add s2_cell_id tags to data that includes fields with latitude and longitude values.

//...
  |> shapeData(
    latField: "latitude",
    lonField: "longitude",
    level: 10
  )

Latitude and longitude values

Flux supports latitude and longitude values in decimal degrees (WGS 84).

Coordinate	Minimum	Maximum
Latitude	-90.0	90.0
Longitude	-180.0	180.0

Region definitions

Many functions in the Geo package filter data based on geographic region. Define geographic regions using the following shapes:

• box
• circle
• point
• polygon

box

Define a box-shaped region by specifying a record containing the following properties:

• minLat: minimum latitude in decimal degrees (WGS 84) (Float)
• maxLat: maximum latitude in decimal degrees (WGS 84) (Float)
• minLon: minimum longitude in decimal degrees (WGS 84) (Float)
• maxLon: maximum longitude in decimal degrees (WGS 84) (Float)

Example box-shaped region

{
  minLat: 40.51757813,
  maxLat: 40.86914063,
  minLon: -73.65234375,
  maxLon: -72.94921875
}

circle

Define a circular region by specifying a record containing the following properties:

• lat: latitude of the circle center in decimal degrees (WGS 84) (Float)
• lon: longitude of the circle center in decimal degrees (WGS 84) (Float)
• radius: radius of the circle in kilometers (km) (Float)

Example circular region

{
  lat: 40.69335938,
  lon: -73.30078125,
  radius: 20.0
}

point

Define a point region by specifying a record containing the following properties:

• lat: latitude in decimal degrees (WGS 84) (Float)
• lon: longitude in decimal degrees (WGS 84) (Float)

Example point region

{
  lat: 40.671659,
  lon: -73.936631
}

polygon

Define a custom polygon region using a record containing the following properties:

• points: points that define the custom polygon (Array of records)

  Define each point with a record containing the following properties:

  - **lat**: latitude in decimal degrees (WGS 84) _(Float)_
  - **lon**: longitude in decimal degrees (WGS 84) _(Float)_
  

Example polygonal region

{
  points: [
    {lat: 40.671659, lon: -73.936631},
    {lat: 40.706543, lon: -73.749177},
    {lat: 40.791333, lon: -73.880327}
  ]
}

GIS geometry definitions

Many functions in the Geo package manipulate data based on geographic information system (GIS) data. Define GIS geometry using the following:

• Any region type (typically point)
• linestring

linestring

Define a geographic linestring path using a record containing the following properties:

• linestring: string containing comma-separated longitude and latitude coordinate pairs (lon lat,):

{
  linestring: "39.7515 14.01433, 38.3527 13.9228, 36.9978 15.08433"
}

Distance units

The geo package supports the following units of measurement for distance:

• m - meters
• km - kilometers (default)
• mile - miles

Define distance units

Use the units option to define custom units of measurement:

import "experimental/geo"

option geo.units = {distance: "mile"}

Options

option geo.units = {distance: "km"}

units

units defines the unit of measurement used in geotemporal operations.

Functions

{{< children type="functions" show="pages" >}}