---
title: geo package
description: The geo package provides tools for working with geotemporal data, such as filtering and grouping by geographic location.
url: https://docs.influxdata.com/flux/v0/stdlib/experimental/geo/
estimated_tokens: 1862
product: Flux
version: v0
publisher: InfluxData
canonical: https://docs.influxdata.com/flux/v0/stdlib/experimental/geo/
date: '2025-02-27T17:50:16-06:00'
lastmod: '2025-02-27T17:50:16-06:00'
---

* Flux 0.63.0+

InfluxDB support

> [!Important]
> The `geo` package is experimental and [subject to change at any time](/flux/v0/stdlib/experimental/#experimental-packages-are-subject-to-change).

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

```js
import "experimental/geo"
```

## Geo schema requirements

The Geo package uses the Go implementation of the [S2 Geometry Library](https://s2geometry.io/).
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](https://s2geometry.io/resources/s2cell_statistics.html).

**Note:** To filter more quickly, use higher S2 Cell ID levels, but know that
higher levels increase [series cardinality](/influxdb/v2/reference/glossary/#series-cardinality).

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

* **Go:** [`s2.CellID.ToToken()`](https://godoc.org/github.com/golang/geo/s2#CellID.ToToken)
* **Python:** [`s2sphere.CellId.to_token()`](https://s2sphere.readthedocs.io/en/latest/api.html#s2sphere.CellId)
* **JavaScript:** [`s2.cellid.toToken()`](https://github.com/mapbox/node-s2/blob/master/API.md#cellidtotoken---string)

### 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.

```no_run
//...
  |> 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](#box)
* [circle](#circle)
* [point](#point)
* [polygon](#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

```no_run
{
  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

```no_run
{
  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

```no_run
{
  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

```no_run
{
  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](#region-definitions) *(typically [point](#point))*
* [linestring](#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,`):

```no_run
{
  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:

```no_run
import "experimental/geo"

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

## Options

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

### units

`units` defines the unit of measurement used in geotemporal operations.

## Functions

* [geo.asTracks()](/flux/v0/stdlib/experimental/geo/astracks/)
* [geo.filterRows()](/flux/v0/stdlib/experimental/geo/filterrows/)
* [geo.getGrid()](/flux/v0/stdlib/experimental/geo/getgrid/)
* [geo.getLevel()](/flux/v0/stdlib/experimental/geo/getlevel/)
* [geo.gridFilter()](/flux/v0/stdlib/experimental/geo/gridfilter/)
* [geo.groupByArea()](/flux/v0/stdlib/experimental/geo/groupbyarea/)
* [geo.s2CellIDToken()](/flux/v0/stdlib/experimental/geo/s2cellidtoken/)
* [geo.s2CellLatLon()](/flux/v0/stdlib/experimental/geo/s2celllatlon/)
* [geo.shapeData()](/flux/v0/stdlib/experimental/geo/shapedata/)
* [geo.ST\_Contains()](/flux/v0/stdlib/experimental/geo/st_contains/)
* [geo.ST\_Distance()](/flux/v0/stdlib/experimental/geo/st_distance/)
* [geo.ST\_DWithin()](/flux/v0/stdlib/experimental/geo/st_dwithin/)
* [geo.ST\_Intersects()](/flux/v0/stdlib/experimental/geo/st_intersects/)
* [geo.ST\_Length()](/flux/v0/stdlib/experimental/geo/st_length/)
* [geo.ST\_LineString()](/flux/v0/stdlib/experimental/geo/st_linestring/)
* [geo.stContains()](/flux/v0/stdlib/experimental/geo/stcontains/)
* [geo.stDistance()](/flux/v0/stdlib/experimental/geo/stdistance/)
* [geo.stLength()](/flux/v0/stdlib/experimental/geo/stlength/)
* [geo.strictFilter()](/flux/v0/stdlib/experimental/geo/strictfilter/)
* [geo.toRows()](/flux/v0/stdlib/experimental/geo/torows/)
* [geo.totalDistance()](/flux/v0/stdlib/experimental/geo/totaldistance/)

#### Related

* [Work with geo-temporal data](/influxdb/v2/query-data/flux/geo/)

[geotemporal](/flux/v0/tags/geotemporal/)
| Coordinate | Minimum | Maximum |
| --- | --- | --- |
| Coordinate | Minimum | Maximum |
| Latitude | -90.0 | 90.0 |
| Longitude | -180.0 | 180.0 |