> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omneo.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Locations
## What are locations?
Locations in Omneo are used to attribute interactions, transactions and customer events. Locations can be physical or virtual stores such as Kiosks, storefronts and eCommerce. Omneo can track users first join locations, preferred location or even most visited location, and can be used to influence incentives. We encourage you to store as much information about a location in Omneo, but as a minimum you'll need to store the name and identifier. It's also important to store the `external_id` which can be referenced by your 3rd party systems such as POS.
See [Locations](/concepts/commerce/locations) for a full explanation of location types, configuration, and how locations relate to transactions and customer profiles.
```json theme={null}
"data": [
{
"id": 1,
"type": "test",
"name": "Main Shop",
"description": "The main store front",
"phone": "0399123314",
"email": "info@test.com",
"timezone": "Australia/Melbourne",
"external_id": "S01",
"external_code": "S01",
"is_published": true,
"is_permanently_closed": false,
"address": {
"id": 10,
"address_line_1": "562 Smith Street",
"address_line_2": "Level 3",
"address_line_3": null,
"company": null,
"latitude": 37.8136,
"longitude": 144.9631,
"city": "St Kilda",
"postcode": "3004",
"state": "VIC",
"country": "Australia",
"notes": "This is the main store",
"external_id": null,
"is_default": false,
"created_at": "2021-02-04 23:22:59",
"updated_at": "2021-02-04 23:22:59"
},
"normal_hours": [
{
"id": 1,
"location_id": 1,
"day_of_week": "MON",
"open_at": "08:00",
"close_at": "18:15",
"created_at": "2021-02-04 23:24:17",
"updated_at": "2021-02-04 23:24:17"
}
],
"special_hours": [
{
"id": 1,
"location_id": 1,
"name": "Christmas Eve",
"is_repeating": 1,
"open_at": "06:00",
"close_at": "15:30",
"start_at": "2020-12-24 00:00:00",
"end_at": "2020-12-24 00:00:00",
"created_at": "2021-02-04 23:24:17",
"updated_at": "2021-02-04 23:24:17"
}
],
"tags": ["main","physical"],
"custom_fields": [],
"created_at": "2020-05-18 08:52:49",
"updated_at": "2021-02-01 02:33:59"
},
{
"id": 2,
"type": "demo",
"name": "Secondary Store",
"description": "this is a secondary store",
"phone": "33114433",
"email": "info@test.com.au",
"timezone": "Australia/Melbourne",
"external_id": "S2",
"external_code": "S2",
"is_published": true,
"is_permanently_closed": false,
"address": null,
"normal_hours": [],
"special_hours": [],
"tags": ["secondary"],
"custom_fields": [],
"created_at": "2020-05-18 08:53:28",
"updated_at": "2020-11-05 12:50:10"
}
]
```
## Location properties
**Storing unknown locations**
If a customer interacts or transacts at a Location with an unknown ‘external ID’ to Omneo, a placeholder Location will be created by Omneo that you can extend with more information later in Omneo CX Manager.
# Location Attributes
| Attribute | Description |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| id `INTEGER` `READ-ONLY` | The unique Omneo ID of the location |
| type `STRING` | A simple string specifying the type of the location Example: "popup", "temp", "kiosk" |
| name `STRING` | The display name of the location |
| description `STRING` | A description of the location |
| phone `STRING` | The primary phone number of the location |
| email `STRING` `EMAIL` | The primary email address for the location |
| timezone `TIMEZONE` | The timezone the location is in. Must be a valid \[timezone] ([https://en.wikipedia.org/wiki/List\_of\_tz\_database\_time\_zones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)) |
| external\_id `STRING` | The external id of the location. This is usually the an external reference for this location in your existing systems outside Omneo |
| external\_code `STRING` | The external code of the location This is usually the location reference code used in your external systems outside Omneo. |
| is\_published `BOOLEAN` | Denotes whether this location is available as a usable location |
| is\_permanently\_closed `BOOLEAN` | Denotes whether this location is permanently closed |
| address `ADDRESS` | The address of the location |
| normal\_hours `ARRAY` | The regularly scheduled hours of operation at the location. |
| special\_hours `ARRAY` | An Array of objects containing special hours. Special hours fall outside the normal hours of operation. These can be recurring, or once off changes to hours. For example: Christmas hours |
| tags `ARRAY` | An array of tags attached to this location |
| custom\_fields `ARRAY` | Custom fields attached to this location |
| created\_at `DATE-TIME` | The UTC date & time the location record was created in ISO 8601 format. |
| updated\_at \`DATE-TIME | The UTC date & time the location record was last updated in ISO 8601 format. |
# Normal Hours
Normal hours define the standard hours of operation for a location.
These are defined by each day of the week, and repeat indefinitely.
### Closing a store with Normal Hours
A store is considered closed if the `open_at` or `close_at` times are not set.
A store is also considered closed if no hours exist for the `day_of_the_week`
# Normal Hours Attributes
| Attribute | Description |
| ------------- | ---------------------------------------- |
| id | The Omneo ID of the normal hour group |
| location\_id | The location the hour group applies to |
| day\_of\_week | The day of week the hours apply |
| open\_at | The location opening time |
| close\_at | The location closing time |
| created\_at | The time the hour group was created |
| updated\_at | The time the hour group was last updated |
# Special Hours
Special hours only apply on the date they are set, and can be set to repeat when needed.
Special hours should be considered before normal hours, when determining the store opening/closing hours.
### Closing a store with special hours
To close a store on a specified date, you can specify a Special Hour group with no `open_at` and `close_at` date. If both dates are empty, the store is considered closed for the duration
# Special Hours Attributes
| | |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| id `INTEGER` | The Omneo ID of the normal hour group |
| location\_id `INTEGER` | The location the hour group applies to |
| name `STRING` | The name for the special hour group |
| is\_repeating `BOOLEAN` | True = This Special Hour group repeats yearly for the specified `start_at` and `end_at` False = This Special Hour group occurs only once, for the specified `start_at` and `end_at` dates and will never occur again. |
| open\_at `DATE-TIME` | The opening time for the location |
| close\_at `DATE-TIME` | The location closing time |
| start\_at `DATE-TIME` | The start date from which these special hours will apply to the location |
| end\_at `DATE-TIME` | The end date from which these special hours will stop applying to the location |
| created\_at `TIMESTAMP` | The time the hour group was created |
| updated\_at `TIMESTAMP` | The time the hour group was last updated |