Documentation

geo package

The geo package is experimental and subject to change at any time.

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:

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

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:

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


Was this page helpful?

Thank you for your feedback!


Introducing InfluxDB Clustered

A highly available InfluxDB 3.0 cluster on your own infrastructure.

InfluxDB Clustered is a highly available InfluxDB 3.0 cluster built for high write and query workloads on your own infrastructure.

InfluxDB Clustered is currently in limited availability and is only available to a limited group of InfluxData customers. If interested in being part of the limited access group, please contact the InfluxData Sales team.

Learn more
Contact InfluxData Sales

The future of Flux

Flux is going into maintenance mode. You can continue using it as you currently are without any changes to your code.

Flux is going into maintenance mode and will not be supported in InfluxDB 3.0. This was a decision based on the broad demand for SQL and the continued growth and adoption of InfluxQL. We are continuing to support Flux for users in 1.x and 2.x so you can continue using it with no changes to your code. If you are interested in transitioning to InfluxDB 3.0 and want to future-proof your code, we suggest using InfluxQL.

For information about the future of Flux, see the following: