Signals

The Signals API gives you access to your account's Signals.

Put simply, a Signal is a named time series of Data Points, which can represent e-commerce transactions, bookings, rentals, footfall or any occurrence relevant to your business or industry.

To access Signals, firstly create a Signal, describing any custom dimensions and information included in your data. Once your Signal has been created, You should upload Data Points. Finally, once sufficient data has been provided, you will be able to access the Signal analysis.

Properties

Property

Description

id string read-only

A unique identifier for the Signal.

E.g. BpBJK358Sbhw

name string

The name of the Signal.

E.g. My Bookings

country string

A country code in ISO 3166-1 alpha 2 format.

E.g. NZ

dimensions array

A list of custom dimensions.

E.g. [{"type": "category", "name": "my_dimension"}]

created_at string read-only

UTC date and time of the Signal's creation in ISO 8601 format.

E.g. 2014-07-16T01:35:26Z

updated_at string read-only

UTC date and time of the last update to the Signal in ISO 8601 format.

E.g. 2015-01-08T03:14:32Z


Retrieve All Signals

It's easy to get a list of all Signals that are associated with your account.


Create a Signal

Before you do anything else, you need to create a new Signal that represents a time series that's important to your business.

Additionally, when creating a Signal, you can define custom dimensions that will help you narrow down your results.

Dimension Properties

Property

Description

name string

The name of the dimension. Please note that names are transformed using underscore notation.

E.g. room_type

type string

The type of dimension.

Possible values:

  • category - For options associated with your Data Points. E.g. a product category, etc.
  • number - For quantities associated with your Data Points. E.g. a quantity, a price, etc.
  • date - For dates that are relevant to your business and are different from the supported types.

E.g. category

Currency as Number

Even though it's possible to store currencies in a dimension of type number, please note that all numbers are stored internally as floats, which means you will encounter rounding issues when you filter your results with a number range.


Retrieve a Signal

This action returns a Signal according to the unique identifier you provide.

Parameters

Attribute

Description

id string

Unique identifier of the Signal.


Update a Signal

This action modifies a Signal according to the unique identifier you provide.

Parameters

Attribute

Description

id string

Unique identifier of the Signal.


Delete a Signal

This action will delete a Signal altogether along with the Data Points associated with it, according to the unique identifier you provide.

Parameters

Parameter

Description

id string

Unique identifier of the Signal.


Create Data Points

Every Signal needs a series of Data Points for the API to do its job.

At the bare minimum, a Data Point is characterised by an identifier that is unique to your business (but multiple Signals can contain the same Data), a date, and a geo-location.

Optionally, Data Points can be given a date at which a transaction was initiated, and a date at which it was completed. This can be used to take into consideration lead time and time span when aligning your Signal with events. This is particularly useful for booking transactions.

Unlike the other endpoints, the Data Point sink accepts three content types for uploading your data:

  • application/json: A JSON array of Data Points.
  • application/x-ldjson: A list of JSON Data Points, one on each line.
  • text/csv: A list of Data Points with each column comma-separated, and column names on the first row.

Parameters

Parameter

Description

id string

Unique identifier of the Signal.

Data Point Properties

Property

Description

uid string

Unique identifier of the transaction.

E.g. 1354861a5

date string

Date of the Data Point in ISO 8601 format. This corresponds to your main date (e.g. Check-in, Pick-up, Transaction, etc.).

E.g. 2015-09-01T00:00:00Z

latitude number

The latitude for the location of the Data Point.

E.g. -27.46846

longitude number

The longitude for the location of the Data Point.

E.g. 153.02342

initiated string

An initiation date in ISO 8601 format. This must be anterior to the date of the Data Point.

E.g. 2015-08-25T00:00:00Z

completed string

A completion date in ISO 8601 format. This must be posterior to the date of the Data Point.

E.g. 2015-09-03T00:00:00Z

{you_name_it} number, date or category

Any extra dimensions defined in the Signal is returned as an additional property.

E.g. Double Room

Geo-Location

Geo-location is compulsory to align your Signal with relevant events. If you don't have or know the exact geo-location for your Data Points, consider using the centre of the city, region or country that is of interest for your business needs.

Number of Records per Request

As a rule of thumb, you should limit the number of records you upload with any single request to 1,000. If you use the CSV format, make sure to repeat the CSV header with each call.


Retrieve All Dimensions

This action returns a summary for each dimension of your Signal.

Parameters

Parameter

Description

id string

Unique identifier of the Signal.


Retrieve Analysis

This action returns a complete analysis of your Signal, which includes what your actual figures were, what could be expected, and what was in excess in terms of demand, lead time and duration and can be explained using events. Note that lead time (lead) and duration (span) analysis are only available when an initiated and completed dates are provided with data points, respectively.

To retrieve a list of events that we estimate impacted your business at a specific date in the past, use the signal.id and signal.explain parameters with the events endpoint.

Alternatively, to retrieve a list of predicted events that we estimate will impact your business in the future, use the signal.id parameter and the date range you wish a prediction for using active or start.

See the events endpoint for more details.

Parameters

Parameter

Description

id string

Unique identifier of the Signal.

date date range

The date range to consider. Supports gt, gte, lt, lte and tz suffixes.

E.g. ?date.gte=2014-12-19&date.lte=2014-12-19

within area

A geo centre and radius in the form {radius}{unit}@{latitude},{longitude}, where the radius unit can be one of: m, km, ft, mi.

E.g. ?within=10km@-36.844480,174.768368

significance number

A number between 0 and 100 representing a significance threshold. Defaults to 50.

E.g. ?significance=99.73

initiated date range

The initiation date range to consider. Supports gt, gte, lt, lte and tz suffixes.

E.g. ?initiated.gte=2014-12-19&initiated.lte=2014-12-19

completed date range

The completion date range to consider. Supports gt, gte, lt, lte and tz suffixes.

E.g. ?completed.gte=2014-12-19&completed.lte=2014-12-19

custom.{custom_category_name} string

A comma-separated list of names. Please note that this is case-sensitive and should match your own values.

E.g. ?custom.room_type=Double+Room,Suite

custom.{custom_date_name} date range

The date range to consider. Supports gt, gte, lt, lte and tz suffixes.

E.g. ?custom.name.gte=2014-12-19&custom.name.lte=2014-12-19

custom.{custom_number_name} numeric range

A custom numeric range to consider. Supports gt, gte, lt, lte suffixes.

E.g. ?custom.name.gte=25&custom.name.lte=30

The significance parameter corresponds to percentage of variation in your data that is considered normal when computing excess that can be attributed to events. If you were to look at a normal distribution, it would correspond to the percentage of values that lie within a band around the mean.

As an example:

  • ~68.27% = 1 standard deviation from the mean
  • ~95.45% = 2 standard deviations from the mean
  • ~99.73% = 3 standard deviations from the mean

A high significance means that only extreme spikes and troughs will be attributed to events. We use 50% as a default, which corresponds to ~0.68 standard deviations.