Geolocation and timezone tracking

Snowplow provides several ways to capture location and timezone information:

• IP-based geolocation: the IP Lookup enrichment adds location data to the geo_ atomic event properties based on the user's IP address.
• Device geolocation: client-side trackers can access GPS coordinates from the device and attach them as an entity. This requires user permission but provides more accurate location data.
• Timezone: most trackers can capture the device timezone and add it to the os_timezone atomic event property.

Location atomic event properties

The IP Lookup enrichment populates the geo_ atomic event properties, based on the IP address of the HTTP request to the event Collector.

Timezone atomic event property

Some Snowplow trackers can populate the os_timezone atomic event field based on the device timezone.

Depending on the tracker, you may need to configure a plugin, set configuration on tracker initialization, or use the tracker Subject class. This table shows the support for timezone tracking across the main Snowplow tracker SDKs:

Tracker	Supported	Since version
Web	✅	3.0.0
iOS	✅	0.1.0
Android	✅	0.1.0
React Native	✅	0.1.0
Flutter	✅	0.1.0
Roku	✅	0.1.0
Node.js	✅	0.8.0
Golang	✅	0.1.0
.NET	✅	0.1.0
Java	✅	0.4.0
Python	✅	0.4.0
Scala	✅	0.1.0
Ruby	✅	0.3.0
Rust	✅	0.1.0
PHP	✅	0.1.0
C++	✅	0.1.0
Unity	✅	0.1.0
Lua	❌
Google Tag Manager	❌

Geolocation entity

Some Snowplow trackers can access device geolocation information, e.g. GPS coordinates, and attach it to events as an entity. This requires permission from the user, but is often more accurate than the IP-based geolocation.

This table shows the support for geolocation tracking across the main client-side Snowplow tracker SDKs. The server-side trackers don't include geolocation tracking.

Tracker	Supported	Since version	Auto-tracking	Notes
Web	✅	3.0.0	✅	Requires timezone plugin
iOS	✅	0.6.0	✅	Set in tracker configuration
Android	✅	0.6.0	✅	Set in tracker configuration
React Native	❌
Flutter	✅	0.1.0	✅	Set in tracker configuration
Roku	❌
Google Tag Manager	✅	v3	❌	Integrates with timezone plugin

The React Native tracker did include geolocation entity configuration in earlier versions. We deprecated it in version 4.

geolocation_context

Entity

Schema for client geolocation contexts

Schema URIiglu:com.snowplowanalytics.snowplow/geolocation_context/jsonschema/1-1-0

Example

json

{
  "latitude": 30.04335623,
  "longitude": 67.59633102,
  "latitude_longitude_accuracy": -24902753.22,
  "altitude": -19459.88,
  "altitude_accuracy": -29970651.08,
  "bearing": 21055653.32,
  "speed": -7127794.98
}

Properties and schema

Table

Property	Description
latitude number	Required.
longitude number	Required.
latitudeLongitudeAccuracy number	Optional.
altitude number	Optional.
altitudeAccuracy number	Optional.
bearing number	Optional.
speed number	Optional.
timestamp integer	Optional.

JSON schema

json

{
  "$schema": "http://iglucentral.com/schemas/com.snowplowanalytics.self-desc/schema/jsonschema/1-0-0#",
  "description": "Schema for client geolocation contexts",
  "self": {
    "vendor": "com.snowplowanalytics.snowplow",
    "name": "geolocation_context",
    "format": "jsonschema",
    "version": "1-1-0"
  },
  "type": "object",
  "properties": {
    "latitude": {
      "type": "number",
      "minimum": -90,
      "maximum": 90
    },
    "longitude": {
      "type": "number",
      "minimum": -180,
      "maximum": 180
    },
    "latitudeLongitudeAccuracy": {
      "type": [
        "number",
        "null"
      ]
    },
    "altitude": {
      "type": [
        "number",
        "null"
      ]
    },
    "altitudeAccuracy": {
      "type": [
        "number",
        "null"
      ]
    },
    "bearing": {
      "type": [
        "number",
        "null"
      ]
    },
    "speed": {
      "type": [
        "number",
        "null"
      ]
    },
    "timestamp": {
      "type": [
        "integer",
        "null"
      ]
    }
  },
  "required": [
    "latitude",
    "longitude"
  ],
  "additionalProperties": false
}