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

title	list_title	description	aliases	menu	weight	flux/v0.x/tags	related	introduced
Flux geo package	geo package	The Flux `geo` package provides tools for working with geo-temporal data, such as filtering and grouping by geographic location. Import the `experimental/geo` package.	/influxdb/v2.0/reference/flux/stdlib/experimental/geo/ /influxdb/cloud/reference/flux/stdlib/experimental/geo/	flux_0_x_ref name parent geo experimental	301	functions package geo	/{{< latest "influxdb" >}}/query-data/flux/geo/	0.63.0

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

import "experimental/geo"

Options

import "experimental/geo"

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

units

Units of distances used in geotemporal operations. Default is km.

Supported units:

• km (kilometers)
• mile (miles)

Functions

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

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 (more information below)
• 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 geo-temporal 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 that higher levels increase [series cardinality](/{{< latest "influxdb" >}}/reference/glossary/#series-cardinality). {{% /note %}}

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 geo-temporal data

Use the geo.shapeData() function 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 Geo package units option to define custom units of measurement:

import "experimental/geo"

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