GuidesHelp Centre
API Reference
Contact

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.

📘

More info about Locations?

Further information about locations can be found on the [Omneo Helpcenter] (https://help.omneo.io/hc/en-au/articles/360001918115-Locations)

"data": [
  {
      "id": 1,
      "type": "test",
      "name": "Main Shop",
      "description": "The main store front",
      "phone": "0399123314",
      "email": "[email protected]",
      "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": "[email protected]",
      "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

AttributeDescription
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)
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

AttributeDescription
idThe Omneo ID of the normal hour group
location_idThe location the hour group applies to
day_of_weekThe day of week the hours apply
open_atThe location opening time
close_atThe location closing time
created_atThe time the hour group was created
updated_atThe 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