LiveReach Media API Reference

The LiveReach Media (LRM) API provides a way for customers to integrate their workflows with LiveReach Media analytics and marketing services. The LRM API is organized around REST. The API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors.

Versioning

LRM will conduct routine updates and maintenance to the API and will strive to ensure that changes to all endpoints documented here are made in a backwards compatible manner. If an API is to be deprecated it will remain in use for at least 30 days to allow time for migration.

Endpoint

Ensure you are accessing the LiveReach Media endpoint using https

https://api.livereachmedia.com/api/v1

Authentication

Authenticating with the LiveReach Media API requires an API key. API keys can be generated by your account manager. Please ensure your API Key is kept secure. Authentication is performed with the Authorization HTTP Header in the format Authorization: Api-Key ${APIKEY}

Example Request

$ curl -H "Authorization: Api-Key abcdefghijklmnopqrstuvwxyz012345" https://api.livereachmedia.com/api/v1/profile

Response & Errors

All responses from the LiveReach Media API will be formatted in the application/json data type, wrapped with a common container JSON object with two keys. The result key will contain meta data about your request and information about the error. The content key will contain the API response.

LiveReach Media uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a forbidden query for your user type, etc.). Codes in the 5xx range indicate an error with LRM's servers.

HTTP status code summary

Code Description
200 - OK Everything worked as expected.
204 - No Content Everything worked as expected - however the server will not send a response.
400 - Bad Request The request was unacceptable, often due to missing a required parameter.
401 - Unauthorized No valid API key provided.
403 - Forbidden The authorization was successful, but the user doesn't have access to this resource.
404 - Not Found The requested resource doesn't exist.
422 - Unprocessable Entity The request was valid, but the options provided resulted in a request that could not be processed.
429 - Too Many Requests Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.

Response Object

{
  "result": {
    "success": boolean, // True if the request succeeded. Will result in a 2xx status code.
    "httpCode": integer, // The HTTP status code for the response.
    "errorCode": string, // The error code for the error, if any.
    "errorMessage": string // A human readable error message describing the error that occurred, if any.
  },
  "content": any // The request API response.
}

Sample successful response.

{
  "result": {
    "success": true,
    "httpCode": 200,
  },
  "content": {
    "foo":"bar"
  }
}

Sample error response.

{
  "result": {
    "success": false,
    "httpCode": 401,
    "errorCode": "SESSION_ID_EXPIRED",
    "errorMessage": "Your session has expired."
  }
}

Pagination

For endpoints that return multiple results, they may, by default limit the amount of items they return. You can paginate through the response by providing the from and limit query parameters.

Example Request

$ curl -H "Authorization: Api-Key abcdefghijklmnopqrstuvwxyz012345" https://api.livereachmedia.com/api/v1/items\?from\=50\&limit\=50

Timestamps

All timestamps sent to the API must be formatted according to the RFC 3399 standard. The API will return all timestamps in UTC.

UTC Timestamp

`YYYY-MM-DDTHH:MM:SS`

Timestamp with Timezone Offset

For UTC + offset
`YYYY-MM-DDTHH:MM:SS%2BHH:MM`

For UTC - offset
`YYYY-MM-DDTHH:MM:SS-HH:MM`

Sample timezone offset (Belgium Timezone)
`YYYY-MM-DDTHH:MM:SS%2B01:00`

Sample timezone offset (EST Timezone)
`YYYY-MM-DDTHH:MM:SS-08:00`

Locations

A location is the place of an install represented by a single address. A location can make up many sites, for example at an airport each terminal may be a site.

Location Object

Attribute Description
id
integer 		Unique identifier for the object.
organization_id
integer 		Unique identifier for the organization that owns this object.
name
string 		Name of this location.
coord
[2]float 		Co-ordinates for this location. The co-ordinate format is [x, y], which means this co-ordinate is [long, lat].
archived
boolean 		Archive status for this location. An archived location will no longer generate metrics.
timezone
string 		Local timezone for this location.
type
string 		Location type - either indoor or outdoor.
status
Status Object 		Status object for this location.
created
timestamp 		Creation time for this location.

Sample Location Object

{
  "id": 1331,
  "organization_id": 1337,
  "name": "Adi's Apartment",
  "coord": [
    -87.9073214,
    41.97416249999999
  ],
  "created": "2017-03-23T17:16:37Z",
  "archived": false,
  "timezone": "America/Chicago",
  "type": "indoor",
  "region": "US",
  "status": {
    "stoplight": "red",
    "devices": {
      "up": 40,
      "down": 0,
      "unknown": 0,
      "total": 40,
      "offline": []
    }
  }
}

List Locations

GET /api/v1/locations

Retrieves a list of all locations. This endpoint supports pagination.

URL Parameters
Parameter Default Description
status false Supply true to also return the location's status information. 
$ curl -H "Authorization: Api-Key abcdefghijklmnopqrstuvwxyz012345" https://api.livereachmedia.com/api/v1/locations
{
  "result": {
    "success": true,
    "httpCode": 200
  },
  "content": [
    LocationObject, LocationObject...
  ]
}

Get a Location

GET /api/v1/locations/{id}

Retrieves the location with the specified id.

URL Parameters
Parameter Default Description
status false Supply true to also return the location's status information. 
$ curl -H "Authorization: Api-Key abcdefghijklmnopqrstuvwxyz012345" https://api.livereachmedia.com/api/v1/locations/7
{
  "result": {
    "success": true,
    "httpCode": 200
  },
  "content": LocationObject
}

Sites

A site is a defined area within a location, tied to a floor plan. Each site has a special zone, called the "default" zone (see the section titled Zones for more info) that encompasses the entire site and generates site-wide metrics.

Site Object

Attribute Description
id
integer 		Unique identifier for the object.
organization_id
integer 		Unique identifier for the organization that owns this object.
location_id
integer 		Unique identifier for the location that this site resides in.
name
string 		Name of this location.
floorplan
string 		A URL to the image floorplan for this site.
width
integer 		The width, in pixels, for this site.
height
integer 		The height, in pixels, for this site.
scale
float 		The pixel-to-foot scale ratio for the floorplan.
archived
boolean 		Archive status for this site. An archived site will no longer generate metrics.
timezone
string 		Local timezone for this site.
status
Status Object 		Status object for this site.
created
timestamp 		Creation time for this site.

Sample Site Object

{
  "id": 1332,
  "organization_id": 1337,
  "location_id": 1331,
  "name": "Bedroom",
  "created": "2017-03-23T17:39:13Z",
  "updated": "2018-08-22T20:02:07Z",
  "floorplan": "https://dr1x7e6lehslf.cloudfront.net/lrm-icon.png",
  "width": 3787,
  "height": 503,
  "scale": 0,
  "timezone": "America/New_York",
  "archived": false
}

List Sites

GET /api/v1/locations/{location_id}/sites

Retrieves a list of all sites for a given location. This endpoint supports pagination.

URL Parameters
Parameter Default Description
status false Supply true to also return the site's status information. 
$ curl -H "Authorization: Api-Key abcdefghijklmnopqrstuvwxyz012345" https://api.livereachmedia.com/api/v1/locations/1331/sites
{
  "result": {
    "success": true,
    "httpCode": 200
  },
  "content": [
    SiteObject, SiteObject...
  ]
}

Get a Site

GET /api/v1/sites/{id}

Retrieves the site with the specified id.

URL Parameters
Parameter Default Description
status false Supply true to also return site's status information. 
$ curl -H "Authorization: Api-Key abcdefghijklmnopqrstuvwxyz012345" https://api.livereachmedia.com/api/v1/sites/1332
{
  "result": {
    "success": true,
    "httpCode": 200
  },
  "content": SiteObject
}

Zones

A zone is a defined area within a site. Metrics and analytics are generated at the zone level - and each site has a special zone, called the "default" zone that encompasses the entire site. The default zone's ID will match the site's ID.

Zone Object

Attribute Description
id
integer 		Unique identifier for the object.
organization_id
integer 		Unique identifier for the organization that owns this object.
location_id
integer 		Unique identifier for the location that this zone resides in.
site_id
integer 		Unique identifier for the site that this zone resides in.
name
string 		Name of this zone.
default_zone
boolean 		Default Zone flag. A default zone is a special zone that encompasses the entire site.
boundary
string 		A GIS Polygon defined by an array of x, y coordinates. The last point will always match the first point.
archived
boolean 		Archive status for this zone. An archived zone will no longer generate metrics.
timezone
string 		Local timezone for this zone.
status
Status Object 		Status object for this zone.
created
timestamp 		Creation time for this zone.

Sample Zone Object

{
  "id": 1339,
  "organization_id": 1337,
  "location_id": 1331,
  "name": "TV Zone",
  "site_id": 1331,
  "created": "2017-03-23T18:42:03Z",
  "updated": "2018-08-22T20:02:08Z",
  "timezone": "America/New_York",
  "archived": false,
  "default_zone": false,
  "boundary": [
    [
      [
        0,
        0
      ],
      [
        844.4500000000002,
        0
      ],
      [
        844.4500000000002,
        502.99999999999994
      ],
      [
        0,
        502.99999999999994
      ],
      [
        0,
        0
      ]
    ]
  ]
}

List Zones

GET /api/v1/sites/{site_id}/zones

Retrieves a list of all zones for a given site. This endpoint supports pagination.

URL Parameters
Parameter Default Description
status false Supply true to also return the zone's status information. 
$ curl -H "Authorization: Api-Key abcdefghijklmnopqrstuvwxyz012345" https://api.livereachmedia.com/api/v1/sites/1332/zones
{
  "result": {
    "success": true,
    "httpCode": 200
  },
  "content": [
    ZoneObject, ZoneObject...
  ]
}

Get a Zone

GET /api/v1/zones/{id}

Retrieves the zone with the specified id.

URL Parameters
Parameter Default Description
status false Supply true to also return the zone's status information. 
$ curl -H "Authorization: Api-Key abcdefghijklmnopqrstuvwxyz012345" https://api.livereachmedia.com/api/v1/zones/1339
{
  "result": {
    "success": true,
    "httpCode": 200
  },
  "content": ZoneObject
}

Metrics

SafeOccupancy

GET /api/v1/zones/{zone_id}/metrics/occupancy

The zone occupancy API provides an interface to retrieve overhead metrics for a given zone. Metrics will be provided near real-time. This endpoint does not support pagination.

URL Parameters
Parameter Default Description
startTime Required The start time for the data in this report.
endTime Required The end time for the data in this report.
metrics Required The measurements that will be included in the report. Can be comma separated or supplied multiple times to be combined for supported queries.
Metrics
Name Description
entries The number of entrances detected by all cameras in this zone.
exits The number of exits detected by all cameras in this zone.
occupancy If every entry and exit into this zone is covered by a LiveReach Media powered camera, then our system can compute occupancy, which is naively entries - exits. This number also factors in occupancy resets and periodic resets.

Response

Returns a JSON object with 2 fields -

  • columns - A description of the columns in this report. The columns will always be your dimensions followed by your metrics.

    • name - The name of the column.
    • columnType - The column type - either metric or dimension.
    • dataType. - The data type of the column (i.e. string, integer)

  • rows - An array of arrays representing the data returned by this request. Each element in the row will correspond to a column in columns.

Get the entries and exits for the last 5 minutes

$ curl -H "Authorization: Api-Key abcdefghijklmnopqrstuvwxyz012345" https://api.livereachmedia.com/api/v1/zones/0000/metrics/occupancy\?startTime\=2021-03-17T05:00:00Z\&endTime\=2021-03-17T05:05:00Z\&metrics\=entries\&metrics\=exits
{
  "result": {
    "success": true,
    "httpCode": 200
  },
  "content": {
    "columns": [
      {
        "name": "timestamp",
        "columnType": "dimension",
        "dataType": "timestamp"
      },
      {
        "name": "entries",
        "columnType": "metric",
        "dataType": "integer"
      },
      {
        "name": "exits",
        "columnType": "metric",
        "dataType": "integer"
      }
    ],
    "rows": [
      [
        "2021-03-17T05:00:00Z",
        1,
        2
      ],
      [
        "2021-03-17T05:01:00Z",
        5,
        6
      ],
      [
        "2021-03-17T05:02:00Z",
        0,
        0
      ],
      [
        "2021-03-17T05:03:00Z",
        0,
        0
      ],
      [
        "2021-03-17T05:04:00Z",
        7,
        3
      ],
    ]
  }
}

Get occupancy for the last 5 minutes

$ curl -H "Authorization: Api-Key abcdefghijklmnopqrstuvwxyz012345" https://api.livereachmedia.com/api/v1/zones/0000/metrics/occupancy\?startTime\=2021-03-17T05:00:00Z\&endTime\=2021-03-17T05:05:00Z\&metrics\=occupancy
{
  "result": {
    "success": true,
    "httpCode": 200
  },
  "content": {
    "columns": [
      {
        "name": "timestamp",
        "columnType": "dimension",
        "dataType": "timestamp"
      },
      {
        "name": "occupancy",
        "columnType": "metric",
        "dataType": "integer"
      }
    ],
    "rows": [
      [
        "2021-03-17T05:00:00Z",
        7
      ],
      [
        "2021-03-17T05:01:00Z",
        8
      ],
      [
        "2021-03-17T05:02:00Z",
        8
      ],
      [
        "2021-03-17T05:03:00Z",
        8
      ],
      [
        "2021-03-17T05:04:00Z",
        4
      ],
    ]
  }
}

Query

GET /api/v1/zones/{zone_id}/metrics/query

The zone query API provides an interface to retrieve computed metrics for a given zone. Metrics will be provided near real-time. For real-time metrics please refer to the zone live API. This endpoint does not support pagination.

URL Parameters
Parameter Default Description
startTime Required* The start time for the data in this report.
endTime Required* The end time for the data in this report.
dimensions none The fields on which the metrics will be grouped and aggregated on. Can be comma separated or supplied multiple times to be combined for supported queries.
metrics Required The measurements that will be included in the report. Can be comma separated or supplied multiple times to be combined for supported queries.

*The startTime and endTime parameter are not required when using the minute dimension.

Dimensions
Name Description
minute Time based metric. Aggregate data at a minutely granularity. Cannot be used together with any other time based metric.
hour Time based metric. Aggregate data at an hourly granularity. Cannot be used together with any other time based metric.
day Time based metric. Aggregate data at a daily granularity. Cannot be used together with any other time based metric.
week Time based metric. Aggregate data at a weekly granularity. Cannot be used together with any other time based metric.
vendor Group results by the recognized device vendor. Only to be used in conjunction with the device_ratio metric.
Metrics
Name Description Supported Dimensions
headcount How many unique people existed within the zone within the given time range? minute*, hour, day, week
new_entrant How many unique people existed within the zone within the given hour? hour
frequency This is a measure of how frequently a single visitor returns to the site/zone within a given time scale, on average hour, day, week
dwellTime At a given moment, how long have the people within the zone been standing in the zone for. minute*, hour, day, week
waitTime How long did the people who entered our zone in a given minute, take to leave the zone? This is a backward looking metric that will update itself as we learn how long people, who entered at a given time, took to leave the zone. minute*, hour, day, week
mean(waitTime) The average waitTime for all visits made to the site/zone in the given time range. (none)
median(waitTime) The median waitTime for all visits made to the site/zone in the given time range. (none)
mode(waitTime) The most common waitTime for all visits made to the site/zone in the given time range. (none)
count(waitTime) The number of visits made to the site/zone in the given time range. (none)
variance(waitTime) The variance in waitTimes for the given time range. (none)
stddev(waitTime) The standard deviation in waitTimes for the given time range. (none)
device_ratio The breakout of device vendors by percentage. hour, day, week, + (vendor)
captureRate The percentage of people that entered the site/zone versus those that passed by. hour, day, week

*Returns the most recent 15 minutes of available data when called with the minute dimension and without the startTime and endTime parameters.

Response

Returns a JSON object with 2 fields -

  • columns - A description of the columns in this report. The columns will always be your dimensions followed by your metrics.

    • name - The name of the column.
    • columnType - The column type - either metric or dimension.
    • dataType. - The data type of the column (i.e. string, integer)

  • rows - An array of arrays representing the data returned by this request. Each element in the row will correspond to a column in columns.

Get the headcount for June

$ curl -H "Authorization: Api-Key abcdefghijklmnopqrstuvwxyz012345" https://api.livereachmedia.com/api/v1/zones/0000/metrics/query\?startTime\=2018-06-01\&endTime\=2018-06-30\&metrics\=headcount\&dimensions\=day
{
  "result": {
    "success": true,
    "httpCode": 200
  },
  "content": {
    "columns": [
      {
        "name": "day",
        "columnType": "dimension",
        "dataType": "timestamp"
      },
      {
        "name": "headcount",
        "columnType": "metric",
        "dataType": "integer"
      }
    ],
    "rows": [
      [
        "2018-06-12T00:00:00Z",
        3181
      ],
      [
        "2018-06-11T00:00:00Z",
        5622
      ],
      [
        "2018-06-10T00:00:00Z",
        5302
      ],
      [
        "2018-06-09T00:00:00Z",
        6104
      ],
      [
        "2018-06-08T00:00:00Z",
        6792
      ],
      [
        "2018-06-07T00:00:00Z",
        6471
      ],
      [
        "2018-06-06T00:00:00Z",
        5305
      ],
      [
        "2018-06-05T00:00:00Z",
        3486
      ],
      [
        "2018-06-04T00:00:00Z",
        1225
      ],
      [
        "2018-06-03T00:00:00Z",
        1567
      ],
      [
        "2018-06-02T00:00:00Z",
        1207
      ],
      [
        "2018-06-01T00:00:00Z",
        534
      ]
    ]
  }
}

Get the headcount for the first 6 hours of June 4th, per hour

$ curl -H "Authorization: Api-Key abcdefghijklmnopqrstuvwxyz012345" https://api.livereachmedia.com/api/v1/zones/0000/metrics/query\?startTime\=2018-06-04T00:00:00\&endTime\=2018-06-04T06:00:00\&metrics\=headcount\&dimensions\=hour
{
  "result": {
    "success": true,
    "httpCode": 200
  },
  "content": {
    "columns": [
      {
        "name": "hour",
        "columnType": "dimension",
        "dataType": "timestamp"
      },
      {
        "name": "headcount",
        "columnType": "metric",
        "dataType": "integer"
      }
    ],
    "rows": [
      [
        "2018-06-04T05:00:00Z",
        4
      ],
      [
        "2018-06-04T04:00:00Z",
        2
      ],
      [
        "2018-06-04T03:00:00Z",
        4
      ],
      [
        "2018-06-04T02:00:00Z",
        5
      ],
      [
        "2018-06-04T01:00:00Z",
        72
      ],
      [
        "2018-06-04T00:00:00Z",
        80
      ]
    ]
  }
}

Get the standard deviation and variance of wait times for June 4th

$ curl -H "Authorization: Api-Key abcdefghijklmnopqrstuvwxyz012345" https://api.livereachmedia.com/api/v1/zones/0000/metrics/query\?startTime\=2018-06-04\&endTime\=2018-06-05\&metrics\=stddev(waitTime),variance(waitTime)
{
  "result": {
    "success": true,
    "httpCode": 200
  },
  "content": {
    "columns": [
      {
        "name": "stddev(waitTime)",
        "columnType": "metric",
        "dataType": "float"
      },
      {
        "name": "variance(waitTime)",
        "columnType": "metric",
        "dataType": "float"
      }
    ],
    "rows": [
      [
        4.723506903555016,
        22.311517467931903
      ]
    ]
  }
}

Get the daily device vendor breakdown

$ curl -H "Authorization: Api-Key abcdefghijklmnopqrstuvwxyz012345" https://api.livereachmedia.com/api/v1/zones/0000/metrics/query\?startTime\=2018-06-04\&endTime\=2018-06-05\&metrics\=device_ratio\&dimensions\=day,vendor
{
  "result": {
    "success": true,
    "httpCode": 200
  },
  "content": {
    "columns": [
      {
        "name": "day",
        "columnType": "dimension",
        "dataType": "timestamp"
      },
      {
        "name": "vendor",
        "columnType": "dimension",
        "dataType": "string"
      },
      {
        "name": "device_ratio",
        "columnType": "metric",
        "dataType": "float"
      }
    ],
    "rows": [
      [
        "2018-10-07T05:00:00Z",
        "Apple,
        0.6342604626982064
      ],
      [
        "2018-10-03T05:00:00Z",
        "Essential Products, Inc.",
        0.0002599428125812321
      ],
      [
        "2018-10-03T05:00:00Z",
        "Rivet Networks",
        0.0002599428125812321
      ],
      [
        "2018-10-08T05:00:00Z",
        "Huawei Technologies Co.,Ltd",
        0.008859357696566999
      ],
      [
        "2018-10-07T05:00:00Z",
        "Lg Electronics (Mobile Communications)",
        0.022544780728844967
      ]
    ]
  }
}
Frequency of the querying the api for daily dimension
Frequency Start times of the job Time for execution Earliest time of the day to query
once every hour Every 35th minute of hour min 2 mins 00:40

Live

GET /api/v1/zones/{zone_id}/metrics/live

The zone live API provides an interface to retrieve the most up to date metrics about a zone. The live API should only be used once the post-installation calibration period has concluded. Please contact a LiveReach Media representative for more information.

URL Parameters
Parameter Default Description
metrics Required The measurements that will be included in the report. Can be comma separated or supplied multiple times to be combined for supported queries.
Metrics
Name Description
headcount How many people are currently in this zone?
waitTime What is the current wait time for people moving through this zone.

Response

Returns a JSON object with 2 fields -

  • columns - A description of the columns in this report. The columns will always be your dimensions followed by your metrics.

    • name - The name of the column.
    • columnType - The column type - either metric or dimension.
    • dataType. - The data type of the column (i.e. string, integer)

  • rows - An array of arrays representing the data returned by this request. Each element in the row will correspond to a column in columns. There will only ever be one row, representing the live values for the metrics requested.

Get the current live headcount and wait time.

$ curl -H "Authorization: Api-Key abcdefghijklmnopqrstuvwxyz012345" https://api.livereachmedia.com/api/v1/zones/0000/metrics/live\?metrics\=headcount\&metrics\=waitTime
{
  "result": {
    "success": true,
    "httpCode": 200
  },
  "columns": [
    {
      "name": "waitTime",
      "columnType": "metric",
      "dataType": "float"
    },
    {
      "name": "headcount",
      "columnType": "metric",
      "dataType": "float"
    }
  ],
  "rows": [
    [
      11.068,
      14
    ]
  ]
}

Path Analysis

Source Path Analysis

GET /api/v1/zones/{zone_id}/metrics/path_analysis/source/1d

The zone source path_analysis API provides a breakout of all of the paths that started at the specified zone.

URL Parameters
Parameter Default Description
startTime* Required The start time for the data in this report.
endTime* Required The end time for the data in this report.
visitorType* Optional A parameter which can take one of the 3 values new | returning | all
zone Required The zone for which the paths are to be included in this report.

*The path_analysis API only honors the date in the startTime and endTime parameters, not the time.

Response

Returns a JSON object with each zone visited represented as a node in a tree with many possible paths, or branches. A node may repeat across the branches.

  • 'zone_id' - A site or zone first visited along a traveler's path. The first zone in the response will always be the input zone, representing the beginning of all of the detected paths.

    • visitors - The percentage of all travelers that were seen at this node, given all of the branches in the tree.
    • children - Returns an array with all of the next possible nodes in travelers' paths. Will return null if this is the last node in the branch.

Get the path analysis for August 9th.

$ curl -H "Authorization: Api-Key abcdefghijklmnopqrstuvwxyz012345" https://api.livereachmedia.com/api/v1/zones/1234/metrics/path_analysis/source/1d\?endTime\=2019-08-10\&startTime\=2019-08-09\&visitorType\=all
{  
   "result":{  
      "success":true,
      "httpCode":200
   },
   "content":[
  {  
          "zone_id":1234,
          "visitors":1.0,
          "children":[  
      {
              "zone_id":3456,
              "visitors":0.75,
              "children":null
      },
      {
              "zone_id":4444,
              "visitors":0.15,
              "children":null
      },
      {
              "zone_id":6666,
              "visitors":0.1,
              "children":null
      }
          ]
  }
   ]
}
Frequency of the querying the api

Frequency of the jobs is Region specific

Region Frequency Start times of the job Time for execution Earliest time of the day to query
EU once every 12 hrs 11:59 UTC,23:59 UTC min 4 hours 16:00
US once every hour Every 45th minute of hour min 2 mins End of hour

All Path Analysis

GET /api/v1/zones/{zone_id}/metrics/path_analysis/all/1d

The zone all path_analysis API provides a breakout of all of the paths that include the specified zone.

URL Parameters
Parameter Default Description
startTime* Required The start time for the data in this report.
endTime* Required The end time for the data in this report.
visitorType* Optional A parameter which can take one of the 3 values new | returning | all
zone Required The zone for which the paths are to be included in this report.

*The path_analysis API only honors the date in the startTime and endTime parameters, not the time.

Response

Returns a JSON object with each zone visited represented as a node in a tree with many possible paths, or branches. A node may repeat across the branches.

  • 'zone_id' - A site or zone visited along a traveler's path. The response will list all paths that included the specified zone.

    • visitors - Returns the percentage of new visitors who start at the zone.
    • children - Returns an array with all of the next possible nodes in travelers' paths. Will return null if this is the last node in the branch.

Get the all path analysis for August 9th.

$ curl -H "Authorization: Api-Key abcdefghijklmnopqrstuvwxyz012345" https://api.livereachmedia.com/api/v1/zones/2815/metrics/path_analysis/all/1d\?endTime\=2019-08-10\&startTime\=2019-08-09\&visitorType\=all
{  
   "result":{  
      "success":true,
      "httpCode":200
   },
   "content": [
      {
         "zone_id": 2815,
         "visitors": 1.0,
         "children": [
            {
            "zone_id": 2817,
            "visitors": 0.65,
            "children": null
            },
            {
            "zone_id": 2827,
            "visitors": 0.35,
            "children": null
            }
         ]
      },
      {
         "zone_id": 6666,
         "visitors": 1.0,
         "children": [
            {
            "zone_id": 2815,
            "visitors": 1.0,
            "children": null
            }
         ]
      },
   ]
}
Frequency of the querying the api

Frequency of the jobs is Region specific

Region Frequency Start times of the job Time for execution Earliest time of the day to query
EU once every 12 hrs 11:59 UTC,23:59 UTC min 4 hours 16:00
US once every hour Every 45th minute of hour min 2 mins End of hour

Cross Path Analysis

GET /api/v1/zones/{zone_id}/metrics/path_analysis/cross/1d

The zone cross_path_analysis API provides a breakout of all of the paths travelled within a "default" zone (site) from start to finish. (“Regardless of where my customer entered from or the other zones they traveled to, this API answers the question: where did they go next ?”)

URL Parameters
Parameter Default Description
startTime* Required The start time for the data in this report.
endTime* Required The end time for the data in this report.
visitorType* Optional A parameter which can take one value all
zone Required The zone for which the paths are to be included in this report. Reports are only generated for "default" zones.

*The path_analysis API only honors the date in the startTime and endTime parameters, not the time.

Response

Returns a JSON object with each zone visited represented as a node in a tree with many possible paths, or branches. A node may repeat across the branches.

  • 'zone_id' - A site or zone visited along a traveler's path. The first zone in the response will always be the input zone, representing the beginning of all of the detected paths.

    • visitors - The percentage of all travelers that were seen at this node, given all of the branches in the tree.
    • children - Returns an array with all of the next possible nodes in travelers' paths. Will return null if this is the last node in the branch.

Get the cross path analysis for August 9th.

$ curl -H "Authorization: Api-Key abcdefghijklmnopqrstuvwxyz012345" https://api.livereachmedia.com/api/v1/zones/1234/metrics/path_analysis/cross/1d\?endTime\=2019-08-10\&startTime\=2019-08-09\&visitorType\=all
{  
   "result":{  
      "success":true,
      "httpCode":200
   },
   "content": [
      {
         "zone_id": 1234,
         "visitors": 1.0,
         "children": [
            {
            "zone_id": 2817,
            "visitors": 0.25,
            "children": null
            }
            {
            "zone_id": 2817,
            "visitors": 0.75,
            "children": null
            }
         ]
      },
   ]
}
Frequency of the querying the api

Frequency of the jobs is Region specific

Region Frequency Start times of the job Time for execution Earliest time of the day to query
EU once every 6 hrs 05:00 ,11:00,17:00.23:00 min 4 hours 09:00
US once every hour Every 35th minute of hour min 2 mins End of hour

Path Analysis

GET /api/v1/zones/{zone_id}/metrics/path_analysis/1d

The zone path_analysis API provides a breakout of all of the paths travelled within a "default" zone (site) from start to finish. (“Regardless of where my customer entered from or the other zones they traveled to, this API answers the question: where did they go next ?”)

URL Parameters
Parameter Default Description
startTime* Required The start time for the data in this report.
endTime* Required The end time for the data in this report.
zone Required The zone for which the paths are to be included in this report. Reports are only generated for "default" zones.

*The path_analysis API only honors the date in the startTime and endTime parameters, not the time.

Response

Returns a JSON object with each zone visited represented as a node in a tree with many possible paths, or branches. A node may repeat across the branches.

  • 'zone_id' - A site or zone visited along a traveler's path. The first zone in the response will always be the input zone, representing the beginning of all of the detected paths.

    • visitors - The percentage of all travelers that were seen at this node, given all of the branches in the tree.
    • children - Returns an array with all of the next possible nodes in travelers' paths. Will return null if this is the last node in the branch.

Get the path analysis for January 16th.

$ curl -H "Authorization: Api-Key abcdefghijklmnopqrstuvwxyz012345" https://api.livereachmedia.com/api/v1/zones/0000/metrics/path_analysis/1d\?endTime\=2019-01-17\&startTime\=2019-01-16
{  
   "result":{  
      "success":true,
      "httpCode":200
   },
   "content":{  
      "zone_id":0000,
      "visitors":1,
      "children":[  
         {  
            "zone_id":0001,
            "visitors":0.77272727272727272,
            "children":[  
               {  
                  "zone_id":0002,
                  "visitors":0.1818181818181819,
                  "children":[  
                     {  
                        "zone_id":0001,
                        "visitors":0.13636363636363635,
                        "children":null
                     }
                  ]
               },
               {  
                  "zone_id":0000,
                  "visitors":0.12727272727272727,
                  "children":[  
                     {  
                        "zone_id":0002,
                        "visitors":0.09090909090909091,
                        "children":[  
                           {  
                              "zone_id":0003,
                              "visitors":0.045454545454545456,
                              "children":[  
                                 {  
                                    "zone_id":0002,
                                    "visitors":0.045454545454545456,
                                    "children":[  
                                       {  
                                          "zone_id":0001,
                                          "visitors":0.045454545454545456,
                                          "children":null
                                       }
                                    ]
                                 }
                              ]
                           },
                           {  
                              "zone_id":0001,
                              "visitors":0.045454545454545456,
                              "children":null
                           }
                        ]
                     },
                     {  
                        "zone_id":0003,
                        "visitors":0.13636363636363635,
                        "children":null
                     }
                  ]
               }
            ]
         }
      ]
   }
}
}

Heatmap

GET /api/v1/zones/{zone_id}/metrics/heatmap

The zone heatmap API returns the specific locations at which visitors were detected with respect to the "default" zone's (site's) floorplan and frequency at which they were seen there. The output enables the creation of a graphical heatmap to visualize the density of visitors within the site.

URL Parameters
Parameter Default Description
startTime* Required The start time for the data in this report.
endTime* Required The end time for the data in this report.
zone Required The zone for which the heatmap data is to be included in this report. Reports are only generated for "default" zones.

*The heatmap API returns data in thirty minute chunks and hence the minimum interval for which it is queried should be thirty minutes.

Response

Returns a JSON object containing an array of coordinates and the corresponding magnitude or frequency of occurrences at that location. Each coordinate represents a location on the floorplan. See the Sites section to learn how to retrieve the floorplan image.

  • x - Assuming the top left of the floorplan is (0,0), the x coordinate, in pixels, of the location at which the visitor was seen.
  • y - Assuming the top left of the floorplan is (0,0), the y coordinate, in pixels, of the location at which the visitor was seen.
  • m - The number of times a visitor was seen at these specific coordinates.

Get the heatmap data for the night of January 29th.

$ curl -H "Authorization: Api-Key abcdefghijklmnopqrstuvwxyz012345" https://api.livereachmedia.com/api/v1/zones/0000/metrics/heatmap\?endTime\=2019-01-29T23:59:59\&startTime\=2019-01-29T22:00:00
{  
   "result":{  
      "success":true,
      "httpCode":200
   },
   "content":[  
      {  
         "x":1414,
         "y":1907,
         "m":1
      },
      {  
         "x":1476,
         "y":1807,
         "m":1
      },
      {  
         "x":1483,
         "y":1794,
         "m":3
      },
      {  
         "x":1542,
         "y":1680,
         "m":1
      },
      {  
         "x":1479,
         "y":1776,
         "m":2
      },
      {  
         "x":1588,
         "y":1592,
         "m":1
      }
   ]
}
Frequency of the querying the api
Frequency Start times of the job Time for execution Earliest time of the day to query
once every 30 mins 0:30 ,01:00,01:30 ... 5 mins(minimum) 01:00

Travel Time

GET /api/v1/zones/{zone_id}/metrics/travel_times/

The zone travel times API provides the average travel time between any two zones.

URL Parameters
Parameter Default Description
startTime* Required The start time for the data in this report.
endTime* Required The end time for the data in this report.
zone_id Required The zone for which the paths are to be included in this report. Reports are not generated for "default" zones or one-way queuing zones.
destination Optional The destination zone for this report. Reports are not generated for "default" zones or one-way queuing zones. If no destination zone is specified travel times to all zones will be included in the report.

*The travel_times API only honors the date in the startTime and endTime parameters, not the current time. </sup>*Valid reports are generated only for time ranges after June 16, 2019

Response

Returns a JSON object with a list of objects that with the average travel time from the zone to the destination zone(s)

Get the travel times from between zones 3456 and 1234 for June 16th.

$ curl -H "Authorization: Api-Key abcdefghijklmnopqrstuvwxyz012345" https://api.livereachmedia.com/api/v1/zones/3456/metrics/travel_times?endTime\=2019-06-17\&startTime\=2019-06-16&destination\=1234
{  
   "result":{  
      "success":true,
      "httpCode":200
   },
   "content":{  
      "3456": {
  "1234": {  
            "avg_time": 2.9615384615384617
         }
      }
   }
}
Frequency of the querying the api

Frequency of the jobs is Region specific

Region Frequency Start times of the job Time for execution Earliest time of the day to query
EU once every 6 hrs 05:30 ,11:30,17:30.23:30 min 2 hours 07:30
US once every hour Every 35th minute of hour min 2 mins End of hour

Status

The status object provides a general description of a locations, site, or zone's status. The status object also includes information about the devices that are down.

Status Object

Attribute Description
stoplight
string 		Either green or red depending on the status of the object.
devices
object 		Unique identifier for the organization that owns this object.
devices.up
integer 		The number of devices that are up.
devices.down
integer 		The number of devices that are down.
devices.total
integer 		The total number of devices in this resource.
devices.offline
array 		The device IDs that are offline.

Sample Status Object

{
  "status": {
    "stoplight": "red",
    "devices": {
      "up": 40,
      "down": 1,
      "unknown": 0,
      "total": 40,
      "offline": [43]
    }
  }
}

Get the status for a Site

$ curl -H "Authorization: Api-Key abcdefghijklmnopqrstuvwxyz012345" https://api.livereachmedia.com/api/v1/sites/5931\?status\=true
{
  "result": {
    "success": true,
    "httpCode": 200
  },
  "content": {
    {
      "id": 5931,
      "status": {
        "stoplight": "red",
        "devices": {
          "up": 40,
          "down": 1,
          "unknown": 0,
          "total": 40,
          "offline": [43]
        }
      }
    }
  }
}