The Ignite Prism REST API provides simple, secure, read-only access to your account's data in JSON format via HTTP GET requests over HTTPS.

Changelog 

2.3

• change API domain name from https://api.prism.com/v2/ to https://api.prismsl.net/v2/

2.2

• add Report Configurations endpoints
• add Reports endpoints
• add Report Data endpoints
• add List of Updated Reports endpoint

2.1

• add Insight Configurations endpoints
• add Insights endpoints

2.0.1

• add Cameras endpoints
• allow some query parameters in the object api to be repeated
• add new query parameters to Sites endpoints

2.0

Backwards incompatible changes

• remove Tripwire Types endpoints and properties (replaced by Data Labels endpoints)
• remove People Counts endpoint (replaced by Data endpoints)

Backwards compatible changes

• add Data Labels endpoints
• add Data endpoints

1.1

• allow the start & stop query parameters on the People Count endpoint to be specified without timezone information to automatically use the site's local timezone
• add optional exclude_imputed query parameter to People Count endpoint
• add optional timezone_mode query parameter to People Count endpoint

1.0

• First stable release of the Ignite Prism API.

Versioning

The Ignite Prism API adheres to the SemVer standard to provide stability to clients integrating with the API.

All urls in the Ignite Prism API include the API major version. The base of all urls of version 2 of the API is https://api.prismsl.net/v2/. 

The major version number will be incremented after backward incompatible changes are introduced to the API. A deprecation period will be provided to allow clients to transition from old versions of the API to newer ones.

Backward compatible changes:

• Adding new endpoints to the API
• Exposing new HTTP methods on existing endpoints
• Adding new properties to existing responses
• Changing query parameters from required to optional

Non-backward compatible changes:

• Renaming or removing endpoints
• Renaming, removing, or altering properties of responses
• Removing HTTP methods on existing endpoints

Authentication

To authenticate to the API, your API key must be included in the HTTP Authorization header. The key should be prefixed by the string literal Token, with whitespace separating the two strings. Only access via HTTPS is allowed.

For example:

curl -H "Authorization: Token <key>"
     "https://api.prismsl.net/v2/accounts/"

Where <key> is to be replaced with your API key. Requests that fail to authenticate will receive an HTTP 401 Unauthorized response.

Keep your key private!

Errors

The Ignite Prism API uses the following HTTP standard error response status codes:

The body of all 4** error responses will be a JSON dictionary describing the error. For example, the body of a 403 Forbidden error response might be:

{
    "error_status_code": 403,
    "error_messages": [
        "you do not have permission to access the requested resource"
    ]
}

The body of 5** error responses will vary and should not be relied on to match any given format.

Sections of the API

The API is broken down into three classes of endpoints.

API Root

Accessing the root of the API, /, will return an object describing the current state of the API.

Properties

Example: retrieve the current state of the api

curl -H "Authorization: Token <key>"
     "https://api.prismsl.net/v2/"

{
    "accounts_url": "https://api.prismsl.net/v2/accounts/",
    "data_url": "https://api.prismsl.net/v2/data/",
    "version": "2.0.1+530-2506c7c"
}

Object API

Overview

Accounts

Endpoints

Query Parameters

Response Properties

Example: list accounts

curl -H "Authorization: Token <key>"
     "https://api.prismsl.net/v2/accounts/"

[
    {
        "id": 1,
        "name": "Project Runway",
        "sites_url": "https://api.prismsl.net/v2/accounts/1/sites/",
        "url": "https://api.prismsl.net/v2/accounts/1/",
        "zones_url": "https://api.prismsl.net/v2/accounts/1/zones/"
    }
]

Sites

Endpoints

Query Parameters

Responses

Example: retrieve details for a site

curl -H "Authorization: Token <key>"
     "https://api.prismsl.net/v2/accounts/1/sites/2/"

{
    "address": {
        "line1": "799 Market St",
        "line2": "8th Floor",
        "city": "San Francisco",
        "postal_code": "94103",
        "province": "California",
        "country_code": "US"
    },
    "business_hours": {
        "monday": {
            "close": "21:00:00",
            "open": "09:00:00"
        },
        "tuesday": {
            "close": "21:00:00",
            "open": "09:00:00"
        },
        "wednesday": {
            "close": "21:00:00",
            "open": "09:00:00"
        },
        "thursday": {
            "close": "21:00:00",
            "open": "09:00:00"
        },
        "friday": {
            "close": "21:00:00",
            "open": "09:00:00"
        },
        "saturday": {
            "close": "21:00:00",
            "open": "09:00:00"
        },
        "sunday": {
            "close": "21:00:00",
            "open": "09:00:00"
        }
    },
    "defined_zone_ids": [4, 5, 32],
    "defined_zones_url": "https://api.prismsl.net/v2/accounts/1/zones/?defined_in_site_id=2",
    "entry_zone_id": 5,
    "entry_zone_url": "https://api.prismsl.net/v2/accounts/1/zones/5/",
    "external_id": "myid",
    "id": 2,
    "name": "Prism Office",
    "reference_image_url": "https://prism-norcal-production.s3.amazonaws.com/1/site-reference-image/2/2015-05-12T15%3A46%3A36.674575%2B00%3A00.jpg?Signature=WmiUCxuR8QbyoJEbeioVO4R%2BOcs%3D&Expires=1435881600&AWSAccessKeyId=AKIAIZG2QTIRLDNE4BIA",
    "timezone": "US/Pacific",
    "url": "https://api.prismsl.net/v2/accounts/1/sites/2/",
    "defined_zone_ids": [
    	"HQ",
    	    "Office"
    ],
    "cameras_url": "https://api.prismsl.net/v2/accounts/1/cameras/?site_id=2"
}

Data Labels

Endpoints

Query Parameters

Response Properties

Example: retrieve details for a Data Label

curl -H "Authorization: Token <key>"
     "https://api.prismsl.net/v2/accounts/1/zones/2/"

{
    "defined_in_site_ids": [8, 9],
    "defined_in_sites_url": "https://api.prismsl.net/v2/accounts/10/sites/?defined_zone_id=2",
    "id": 2,
    "name": "entry",
    "url": "https://api.prismsl.net/v2/accounts/10/zones/2/"
}

Cameras

Endpoints

Query Parameters

Responses

Example: retrieve details for a camera

curl -H "Authorization: Token <key>"
     "https://api.prismsl.net/v2/accounts/1/cameras/8/"

{
 "id": 8,
 "name": "Kitchen Area",
 "is_online": true,
 "url": "https://api.prismsl.net/v2/accounts/1/cameras/8/",
 "image_url": "https://prism-norcal-qa.s3.amazonaws.com/10/views/110/background/2013/02/14/110-background-20130214T214419.419000Z.jpg?",
 "labels": [
     {
         "name": "Food"
      },
      {
          "name": "Fridge"
      }
  ],
 "site_id": 12,
 "site_name": "The Office",
 "site_url": "https://api.prismsl.net/v2/accounts/1/sites/2/"
 "is_videocache_enabled": false
}

Insight Configurations

Endpoints

Responses

Example: retrieve details for a camera

curl -H "Authorization: Token <key>"
     "https://api.prismsl.net/v2/accounts/1/insight-configurations/2/"

{
        "id": 2,
	"name": "Weekly activity",
	"url": "https://api.prismsl.net/v2/accounts/1/cameras/8/",
	"insights_url": "https://api.prismsl.net/v2/accounts/1/insight-configurations/2/insights/"
}

Insights

Endpoints

Query Parameters

Responses

Example: Retrieve a list of Insights

curl -H "Authorization: Token <key>"
     "https://api.prismsl.net/v2/accounts/1/insight-configurations/2/insights/?page=1"

{
        "count": 1,
	"next": null,
	"previous": null,
	"results": [{
	   "id": 2,
	   "week_start_date": "2014‐01‐01",
	   "url": "https://api.prismsl.net/v2/accounts/1/insight‐configurations/2/insights/1/",
	   "image_url": "https://prism‐norcal‐qa.s3.amazonaws.com/1/insight‐config/2/insights/2014/01/07/110‐background‐20130214T214419.419000"
	}]
}

Example: Retrieve details for an Insight

curl -H "Authorization: Token <key>" "https://api.prismsl.net/v2/accounts/1/insight-configurations/2/insights/1/"

{
        "count": 2,
	"week_start_date": "2014‐01‐01",
	"url": "https://api.prismsl.net/v2/accounts/1/insight-configurations/2/insights/1/",
	"image_url": "https://prism-norcal-qa.s3.amazonaws.com/1/insight-config/2/insights/2014/01/07/110-background-20130214T214419.4190000"
}

Example: Retrieve details for an Insight by week start date 

curl -H "Authorization: Token <key>" "https://api.prismsl.net/v2/accounts/1/insight-configurations/2/insights/start_date/2016-11-27/"

{
        "count": 2,
	"week_start_date": "2016-11-27",
	"url": "https://api.prismsl.net/v2/accounts/1/insight-configurations/2/insights/1/",
	"image_url": "https://prism-norcal-qa.s3.amazonaws.com/1/insight-config/2/insights/2014/01/07/110-background-20130214T214419.4190000"
}

Report Configurations

Endpoints

Responses

Either an array of Report Configuration objects, or a single Report Configuration object. Each Report Configuration object has the following properties:

Example: Retrieve details for a Report Configuration

curl -H "Authorization: Token <key>"
     "https://api.prismsl.net/v2/accounts/1/report-configurations/2/"

{
    "id": 2, 
    "name": "Entry Count for Prism Office", 
    "account_id": 1, 
    "url": "https://api.prismsl.net/v2/accounts/1/report-configurations/2/", 
    "site_filters": {
            "site_ids": [
                1017
            ], 
            "site_name": [
                "Prism Office"
            ]
    }, 
    "recurrence_period": "DAILY", 
    "recurrence_frequency": 1, 
    "start": "2018-11-01", 
    "stop_by_date": null, 
    "stop_by_runs": null, 
    "hours": null, 
    "created_at": "2018-11-26T20:26:44.079112Z", 
    "disabled_at": null, 
    "number_of_reports": 31, 
    "most_recent_report_url": "https://api.prismsl.net/v2/accounts/1/report-configurations/2/reports/2018-12-01/", 
    "report_configs_url": "https://api.prismsl.net/v2/accounts/1/report-configurations/"
}

Reports

Endpoints

Responses

Either an array of Report objects, or a single Report object. Report object by start date has the following properties:

Example: Retrieve details for a Report by start date

curl -H "Authorization: Token <key>"
     "https://api.prismsl.net/v2/accounts/1/report-configurations/2/reports/2018-11-26/”

{
        "id": 234, 
        "url": "https://api.prismsl.net/api/v2/accounts/1/report-configurations/2/reports/2018-11-26/", 
        "start": "2018-11-26", 
        "stop": "2018-11-26", 
        "generated_at": "2018-11-25T23:26:44.079112Z", 
        "report_config": {
            "url": "https://api.prismsl.net/api/v2/accounts/1/report-configurations/2/", 
            "recurrence_frequency": 1, 
            "recurrence_period": "DAILY", 
            "id": 2, 
            "name": "Entry Count for Prism Office"
        }, 
        "sites": [
            {
                "url": "https://api.prismsl.net/api/v2/accounts/1/sites/1017/", 
                "id": 1017, 
                "name": "Prism Office"
            }
        ], 
        "site_filters": [
            "Selected Sites: Prism Office"
        ], 
        "zones": [
            {
                "url": "https://api.prismsl.net/v2/accounts/1/zones/6/", 
                "id": 6, 
                "name": "entry"
            }
        ], 
        "metrics": [
            "COUNT"
        ], 
        "by_period_data_url": "https://api.prismsl.net/v2/accounts/1/report-configurations/2/report_data/234/by-period/", 
        "by_region_data_url": "https://api.prismsl.net/v2/accounts/1/report-configurations/2/report_data/234/by-region/", 
        "prev_report_url": "https://api.prismsl.net/v2/accounts/1/report-configurations/2/reports/2018-11-26/", 
        "next_report_url": "https://api.prismsl.net/v2/accounts/1/report-configurations/2/reports/2018-11-27/", 
        "has_valid_data": true, 
        "zone_metrics": [
            "Count: entry"
        ]
    }

Example: List of Reports within start & stop dates

curl -H "Authorization: Token <key>"
     "https://api.prismsl.net/v2/accounts/1/report-configurations/2/reports/2018-11-25/2018-11-26”

    {
        "id": 233,
        "url": "https://api.prismsl.net/api/v2/accounts/1/report-configurations/2/reports/233/",
        "start_date": "2018-11-25",
        "stop_date": "2018-11-25",
        "by_period_data_url": "https://api.prismsl.net/v2/accounts/1/report-configurations/2/report_data/233/by-period/",
        "by_region_data_url": "https://api.prismsl.net/v2/accounts/1/report-configurations/2/report_data/233/by-region/"
    },
    {
        "id": 234,
        "url": "https://api.prismsl.net/api/v2/accounts/1/report-configurations/2/reports/234/",
        "start_date": "2018-11-26",
        "stop_date": "2018-11-26",
        "by_period_data_url": "https://api.prismsl.net/v2/accounts/1/report-configurations/2/report_data/234/by-period/",
        "by_region_data_url": "https://api.prismsl.net/v2/accounts/1/report-configurations/2/report_data/234/by-region/"
    }

Report Data

Data by-period

Endpoints

Query Parameters

Data by-region

Endpoints

Query Parameters

JSON Formatted Response

{
    "columns": [<column 1 header as str>, <column 2 header as str>, ...],
  "rows": [
    [<cell 1x1 value as int/float/str>, <cell 1x2 value as int/float/str>, ...],
    [<cell 2x1 value as int/float/str>, <cell 2x2 value as int/float/str>, ...],
  ]
}

CSV Formatted Response

<column 1 header>,<column 2 header>, ...
<cell 1x1 value>,<cell 1x2 value>, ...
<cell 2x1 value>,<cell 2x2 value>, ...

Examples

curl -H "Authorization: Token <key>"
     "https://api.prismsl.net/v2/accounts/1/report-configurations/2/reports/1/data/by-period/?period=day”

{
  "columns": 'Time Period', 'State/Province', 'Country', 'Entry Count'],
  "rows": [
    ["2015-01-02", 'Site 1', 'CA', 'USA', 4],
    ["2015-01-02", 'Site 2', 'NY', 'USA', 2],
    ["2015-01-03", 'Site 1', 'CA', 'USA', 2],
    ["2015-01-03", 'Site 2', 'NY', 'USA', 16],
  ],
}

curl -H "Authorization: Token <key>"
     "https://api.prismsl.net/v2/accounts/1/report-configurations/2/reports/1/data/by-region/?region=province&format_type=csv”

State/Province,Country,Entry Count
CA,USA,6
NY,USA,18

List of Updated Reports

Endpoints

Example

curl -H "Authorization: Token <key>"
     "https://api.prismsl.net/v2/accounts/1/report-configurations/2/reports/changed-since/2018-11-25T12:00/”

{
        "id": 234,
        "url": "https://api.prismsl.net/api/v2/accounts/1/report-configurations/2/reports/234/",
        "start_date": "2018-11-26",
        "stop_date": "2018-11-26",
        "by_period_data_url": "https://api.prismsl.net/v2/accounts/1/report-configurations/2/report_data/234/by-period/",
        "by_region_data_url": "https://api.prismsl.net/v2/accounts/1/report-configurations/2/report_data/234/by-region/"
    },
    {
        "id": 233,
        "url": "https://api.prismsl.net/api/v2/accounts/1/report-configurations/2/reports/233/",
        "start_date": "2018-11-25",
        "stop_date": "2018-11-25",
        "by_period_data_url": "https://api.prismsl.net/v2/accounts/1/report-configurations/2/report_data/233/by-period/",
        "by_region_data_url": "https://api.prismsl.net/v2/accounts/1/report-configurations/2/report_data/233/by-region/"
    }

Data API

Metrics

A data metrics defined what type of data is being queried from the API. Not every metric is available on every endpoint. Available metrics include:

• count
• avg_dwell
• avg_occupancy

Business Hours

If the client would like the data queries to only consider data in for the business hours of the Site(s) in question, they may specify business_hours_only=True. This has the following effect on the data queries:

• queries whose time range is fully within business hours are unaffected
• for queries whose time range is partially within business hours and partially outside of business hours, only the values within business hours will be considered.
• for queries whose time range is fully outside of business hours, values will be returned as null.

Datetimes and Timezones

The client must use the query parameters start and stop to specify the range of time they would like the data quer(y/ies) to extend over. The following applies to the start and stop parameters:

• they must be specified in ISO 8601 format
• they may include timezone information. If they don't, then the timezone of the Site being queried will be assumed.
• they must be 'snapped' to the 15-minutes (or, in the case of the /by-time/ endpoint, the period). For example: 2015-01-07T09:45:00 is an acceptable value, while 2015-01-07T09:49:56 is not.

Daylight Savings Time Transitions

Working in local timezones that have DST transitions introduces a 'missing hour' and a 'duplicate hour'. The 'missing hour' occurs in the spring in the northern hemisphere, while the 'duplicate hour' occurs in the fall.

If the client chooses to specify a start or stop value without a timezone (thus requesting the Site's timezone be used), if that value cannot be converted into a specific moment in time, a 400 error will be returned. For example, specifying a time of 2014-11-02T01:30:00 for a Site in US/Pacific timezone is ambiguous, since this time occurred twice. Similarly, specifying 2015-03-08T02:30:00 for a Site in US/Pacific timezone does not make sense, as this time never occurred.

For /by-time/ queries with period hour or minute-15 that extend over a DST transition, results in the 'missing hour' will have value null. Results in the 'duplicate hour' will be aggregated together.

Endpoint Overview

Basic data query

Endpoint

Query Parameters

Response

An object whose keys will corresponds to the requested metrics.

Example: retrieve count for a week during business hours for a defined Data Label

curl -H "Authorization: Token <key>"
     "https://api.prismsl.net/data/?zone_id=1&site_id=2&metric=count&business_hours_only=true&start=2014-12-01T00:00:00&stop=2014-12-08T00:00:00"

{
    "count": 424
}

Query over a range of time

Endpoint

Query Parameters

Response

An array of objects, each object corresponding to having run a query for the requested metric(s) over one period of time in between the query parameters start and stop. The start and stop keys in the returned object will each be ISO 8601 datetimes localized to the timezone of the Site in question.

Example: retrieve dwell each hour over a morning

curl -H "Authorization: Token <key>"
     "https://api.prismsl.net/data/?zone_id=1&site_id=2&metric=count&metric=avg_dwell&period=hour&business_hours_only=true&start=2014-12-01T07:00:00&stop=2014-12-01T12:00:00"

[
    {
        "start": "2014-12-01T07:00:00",
        "stop": "2014-12-01T08:00:00",
        "count": null,
        "avg_dwell": null
    }, {
        "start": "2014-12-01T08:00:00",
        "stop": "2014-12-01T09:00:00",
        "count": 10,
        "avg_dwell": 2.41
    }, {
        "start": "2014-12-01T09:00:00",
        "stop": "2014-12-01T10:00:00",
        "count": 23,
        "avg_dwell": 4.22
    }, {
        "start": "2014-12-01T10:00:00",
        "stop": "2014-12-01T11:00:00",
        "count": 27,
        "avg_dwell": 3.45
    }, {
        "start": "2014-12-01T11:00:00",
        "stop": "2014-12-01T12:00:00",
        "count": 26,
        "avg_dwell": 3.21
    }
]

Query over multiple Sites

Endpoint

Query Parameters

Response

An array of objects, each object corresponding to having run a query for the requested metric(s), time period, and Data Label for a particular Site. If the Data Label is not defined for a particular requested Site, null will be returned for all values for that Site.

Example: retrieve count data from for a week for three Sites, one of which doesn't define that Data Label

curl -H "Authorization: Token <key>"
     "https://api.prismsl.net/data/?zone_id=1&site_id=2&site_id=7&site_id=8&metric=count
                                 &start=2014-12-01T00:00:00&stop=2014-12-08T00:00:00"

[
    {
        "site_id": 2,
        "count": 42
    }, {
        "site_id": 7,
        "count": null
    }, {
        "site_id": 8,
        "count": 21
    }
]

Query over multiple Data Labels

Endpoint

Query Parameters

Response

An array of objects, each object corresponding to having run a query for the requested metric(s), time period, and Site for a particular Data Label. If the Data Label is not defined for a particular requested Site, null will be returned for all values for that Data Label.

Example: retrieve counts for a week from three Data Labels defined by a particular Site

curl -H "Authorization: Token <key>"
     "https://api.prismsl.net/data/?site_id=2&zone_id=2&zone_id=18&zone_id=19&metric=count&start=2014-12-01T00:00:00&stop=2014-12-08T00:00:00"

[
    {
        "zone_id": 2,
        "count": 32
    }, {
        "zone_id": 18,
        "count": 10
    }, {
        "zone_id": 19,
        "count": 22
    }