The Location object is a crucial component for enriching semantic events with geographical context. Understanding where an event occurs is fundamental to a wide range of analytics, from market segmentation and logistics to personalization and fraud detection. Location data works particularly well with involves to understand which entities are associated with specific places.
An event can be associated with multiple locations. For instance, a Product Shipped event could have one location object for the origin warehouse and another for the customer's destination address. For this reason, location data is sent as an array of Location objects within the main event payload.
"location": [ { ... location object 1 ... }, { ... location object 2 ... } ]
Location Properties
The Location object contains a mix of properties that can be provided explicitly by the user for maximum accuracy, and properties that can be automatically populated by the Context Suite backend based on other available data (like an IP address or specific coordinates).
| Property | Description | Provided By |
|---|---|---|
location_of | A string describing the role of this location in the event (e.g., "Customer", "Home Address", "Origin Warehouse"). | User-Provided |
label | A human-readable label for the location (e.g., "Headquarters", "Street name 1, 1234"). | User-Provided (Optional) |
street | The street name of the location. | User-Provided (Optional) |
street_nr | The street number of the location. | User-Provided (Optional) |
address | The full, formatted address string. | User-Provided (Optional) |
postal_code | The postal code (e.g., "101"). | User-Provided (Optional) |
postal_name | The name of the postal area (e.g., "Vesturbær"). | User-Provided (Optional) |
longitude | The longitude coordinate. Providing this allows for precise mapping. | User-Provided (Optional) |
latitude | The latitude coordinate. Providing this allows for precise mapping. | User-Provided (Optional) |
duration_from | The start date/time if the location is temporary or valid for a specific period. | User-Provided (Optional) |
duration_until | The end date/time if the location is temporary or valid for a specific period. | User-Provided (Optional) |
country | The name of the country (e.g., "Iceland"). | Auto-Populated |
country_code | The two-letter country code (e.g., "IS"). | Auto-Populated |
region | The region or state (e.g., "Gullbringu og kjósarsýsla"). | Auto-Populated |
division | A smaller administrative division. | Auto-Populated |
municipality | The municipality or city (e.g., "Reykjavik"). | Auto-Populated |
locality | A more specific locality or neighborhood (e.g., "Vesturbær"). | Auto-Populated |
geohash | A geohash generated from longitude and latitude for spatial indexing. | Auto-Populated |
code | A generic code for the location. | User-Provided (Optional) |
Note on Auto-Population: Fields marked Auto-Populated are typically derived by Context Suite's servers from the user's IP address or from longitude/latitude coordinates if they are provided. You can override these auto-populated values by providing them explicitly in your event payload for greater accuracy.
Example Usage
Here is an example of a Product Delivered event that includes two location objects: one for the warehouse it was sent from, and one for the customer's home where it was delivered.
1jitsu.track('Product Delivered', {
2 "location": [
3 {
4 "location_of": "Origin Warehouse",
5 "label": "Main Distribution Center",
6 "postal_code": "220",
7 "municipality": "Hafnarfjörður",
8 "country_code": "IS"
9 },
10 {
11 "location_of": "Customer Delivery",
12 "label": "Customer Home",
13 "street": "Laugavegur",
14 "street_nr": "101",
15 "postal_code": "101",
16 "municipality": "Reykjavík",
17 "country_code": "IS"
18 }
19 ]
20 });