API Reference

The FastSensor API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.
You can use the FastSensor API in test mode, which does not affect your live data or interact with the banking networks. The API key and the server you use to authenticate the request determines whether the request is live mode or test mode.
Once you've registered your client it's easy to start requesting data from FastSensor.
All endpoints are only accessible via https and are located at api.fastsensor.us. For instance: you can test the API by accessing the following URL:
https://api.fastsensor.us/v1/ping?client_id=CLIENT-ID
The endpoints require an access_token for the authenticated users.

Limits

Be nice. If you're sending too many requests too quickly, we'll send back a 503 error code (server unavailable). You are limited to 5000 requests per hour per client_id overall. Practically, this means you should (when possible) authenticate users so that limits are well outside the reach of a given user.

Structure

The Envelope

Every response is contained by an envelope. That is, each response has a predictable set of keys with which you can expect to interact:
{
    "meta": {
        "code": 200
    },
    "data": {
        ...
    },
    "pagination": {
        "next_url": "...",
        "next_max_id": "13872296"
    }
}

META

The meta key is used to communicate extra information about the response to the developer. If all goes well, you'll only ever see a code key with value 200. However, sometimes things go wrong, and in that case you might see a response like:
{
    "meta": {
        "error_type": "OAuthException",
        "code": 400,
        "error_message": "..."
    }
}

DATA

The data key is the meat of the response. It may be a list or dictionary, but either way this is where you'll find the data you requested.

PAGINATION

Sometimes you just can't get enough. For this reason, we've provided a convenient way to access more data in any request for sequential data. Simply call the url in the next_url parameter and we'll respond with the next set of data.
{
    ...
    "pagination": {
        "next_url": "https://api.fastsensor.us/v1/data/recent?access_token=2e77d.47a0479900504cb3ab4a1f626d174d2d&max_id=13872296",
        "next_max_id": "13872296"
    }
}
On views where pagination is present, we also support the "count" parameter. Simply set this to the number of items you'd like to receive. Note that the default values should be fine for most applications - but if you decide to increase this number there is a maximum value defined on each endpoint.

Authentication

OAuth 2.0 Bearer Token

All endpoint requests must include a Bearer Token, a predominant type of access token used with OAuth 2.0. A Bearer Token is an opaque string, not intended to have any meaning to clients using it.

How to generate your Bearer Token

Use the previously obtained API key and the Client ID to request your Bearer Token by accessing the following URL:
https://api.fastsensor.us/oauth2/token?client_id=CLIENT-KEY&api_key=API-KEY
And the response will look like:
{
  "token_type": "bearer",
  "access_token": "2e77d.47a0479900504cb3ab4a1f626d174d2d"
}
Note: Bearer Token will expire within two hours and you should require a new token for each session.

API Methods & Endpoints

Ping

  • /ping
Checks if the API service is running.
curl -X GET "https://api.fastsensor.us/v1/ping?client_id=CLIENT-ID"
RESPONSE:
  • Status: 200 - OK
{
    "meta": {
        "code": 200
    },
    "data": "pong"
}

Get Locations

  • /locations
Get the list of locations.
curl -X GET "https://api.fastsensor.us/v1/locations"
RESPONSE:
  • Status: 200 - OK
{
    "data": [
        {
            "id": Location ID (string),
            "corporation": Name of Corporation (string),
            "name": Location name (string),
            "featured": (boolean),
        }
    ]
}
  • Status: 401 - Access token is missing or invalid

Get Location By ID

  • /locations/{location-id}
Get information about a location.
curl -X GET "https://api.fastsensor.us/v1/locations/{location-id}"
Path Parameter
Description
Required
location-id
The location ID (string)
Yes
RESPONSE:
  • Status: 200 - OK
{
    "data": {
        "id": Location ID (string),
        "corporation": Name of Corporation (string),
        "name": Location name (string),
        "featured": (boolean),
    }
}
  • Status: 401 - Access token is missing or invalid 

Get Foot Traffic

  • /locations/{location-id}/foot-traffic
Retrieve location's foot traffic information for a period.
curl -X GET "https://api.fastsensor.us/v1/locations/{location-id}/foot-traffic?start_date=&end_date=&aggregate=&hour_details="
Path Parameter
Description
Required
location-id
The location ID (string)
Yes
Query Parameter
Description
Required
start_date
Return results for a period starting at given a date
(date, format YYYY-MM-DD)
No
end_date
Return results for a period ending at given a date
(date, format YYYY-MM-DD)
No
aggregate
Define aggregation function (sum or average), otherwise list all items
(string, enum [sum, avg])
No
hour_details
List details per hour
(boolean)
No
RESPONSE:
  • Status: 200 - OK
{
    "data": [
        {
            "date": Date (string, date, format YYYY-MM-DD),
            "walk_by": Number of people passing by the location that date (number),
            "walk_in": Number of people detected by the door counter that date (number),
            "visitors": Number of qualified visitors to the location that date (number),
            "engagers": Number of qualified engagers, subset of visitors (number),
            "browsers": Number of qualified browsers, subset of visitors (number),
            "avg_visit_duration": Average visit duration in minutes
(number),
            "hour_details": [
                {
                    "hour": Hour (00-23) (number),
                    "walk_by": Number of people passing by the location that hour (number),
                    "walk_in": Number of people detected by the door counter that hour (number),
                    "visitors": Number of qualified visitors to the location that hour (number)
                }
            ]
        }
    ]
}
  • Status: 401 - Access token is missing or invalid
Note: Each request is limited to 92 days of dat.

Get Dwell Areas

  • /locations/{location-id}/dwell-areas
Retrieve location's dwell for each area for a period.
curl -X GET "https://api.fastsensor.us/v1/locations/{location-id}/dwell-areas?start_date=&end_date=&aggregate=&hour_details="
Path Parameter
Description
Required
location-id
The location ID (string)
Yes
Query Parameter
Description
Required
start_date
Return results for a period starting at given a date
(date, format YYYY-MM-DD)
No
end_date
Return results for a period ending at given a date
(date, format YYYY-MM-DD)
No
aggregate
Define aggregation function (sum or average), otherwise list all items
(string, enum [sum, avg])
No
hour_details
List details per hour
(boolean)
No
RESPONSE:
  • Status: 200 - OK
{
    "data": [
        {
            "date": Date (string, date, format YYYY-MM-DD),
            "areas": [
                {
                    "area": Area name (string),
                    "visitors": Number of visitors to the area that date (number),
                    "avg_dwell_time": Average dwell time in minutes
(number),
                    "hour_details": [
                        {
                            "hour": Hour (00-23) (number),
                            "visitors": Number of visitors to the area that hour (number)
                        }
                    ]
                }
            ]
        }
    ]
}
  • Status: 401 - Access token is missing or invalid
Note: Each request is limited to 92 days of data.

Get Dwell Group Areas

  • /locations/{location-id}/dwell-group-areas
Retrieve location's dwell for each group of areas for a period.
curl -X GET "https://api.fastsensor.us/v1/locations/{location-id}/dwell-group-areas?start_date=&end_date=&aggregate="
Path Parameter
Description
Required
location-id
The location ID (string)
Yes
Query Parameter
Description
Required
start_date
Return results for a period starting at given a date
(date, format YYYY-MM-DD)
No
end_date
Return results for a period ending at given a date
(date, format YYYY-MM-DD)
No
aggregate
Define aggregation function (sum or average), otherwise list all items
(string, enum [sum, avg])
No
RESPONSE:
  • Status: 200 - OK
{
    "data": [
        {
            "date": Date (string, date, format YYYY-MM-DD),
            "groups": [
                {
                    "group": Group name (string)
                    "visitors": Number of visitors to the group of areas that date (number),
                    "avg_dwell_time": Average dwell time in minutes
(number),
                }
            ]
        }
    ]
}
  • Status: 401 - Access token is missing or invalid
Note: Each request is limited to 92 days of data.

Get Devices

  • /locations/{location-id}/devices
Retrieve a list of visitors' device manufacturers.
curl -X GET "https://api.fastsensor.us/v1/locations/{location-id}/devices?start_date=&end_date=&aggregate="
Path Parameter
Description
Required
location-id
The location ID (string)
Yes
Query Parameter
Description
Required
start_date
Return results for a period starting at a given date
(date, format YYYY-MM-DD)
No
end_date
Return results for a period ending at a given date
(date, format YYYY-MM-DD)
No
aggregate
Define aggregation function (sum or average), otherwise list all items
(string, enum [sum, avg])
No
RESPONSE:
  • Status: 200 - OK
{
    "data": [
        {
            "date": Date (string, date, format YYYY-MM-DD),
            "devices": [
                {
                    "brand": Device brand (string)
                    "percentage": % of visitors carrying devices that brand (number),
                }
            ]
        }
    ]
}
  • Status: 401 - Access token is missing or invalid
Note: Each request is limited to 92 days of data.

Get Alerts

  • /locations/{location-id}/alerts
Retrieve a list of triggered alerts.
curl -X GET "https://api.fastsensor.us/v1/locations/{location-id}/alerts?start_date=&end_date=&selector="
Path Parameter
Description
Required
location-id
The location ID (string)
Yes
Query Parameter
Description
Required
start_date
Return results for a period starting at given a date
(date, format YYYY-MM-DD)
No
end_date
Return results for a period ending at given a date
(date, format YYYY-MM-DD)
No
selector
Define a filter for the alerts
(string)
No
RESPONSE:
  • Status: 200 - OK
{
    "data": [
        {
            "timestamp": Timestamp (number, epoch time in seconds),
            "tag_id": Tag ID if available,
            "alert": Alert description (string),
            "duration": Alert duration in minutes (number),
            "details": Additional information (string)
        }
    ]
}
  • Status: 401 - Access token is missing or invalid
Note: Each request is limited to 92 days of data.

Get Tags

  • /locations/{location-id}/tags
Retrieve the list of tags.
curl -X GET "https://api.fastsensor.us/v1/locations/{location-id}/tags"
Path Parameter
Description
Required
location-id
The location ID (string)
Yes
RESPONSE:
  • Status: 200 - OK
{
    "data": [
        {
            "tag_id": Tag ID if available,
            "last_communication": Timestamp (number, epoch time in seconds),
            "battery": Last meadured battery level (number),
            "active": (boolean),
        }
    ]
}
  • Status: 401 - Access token is missing or invalid

Next steps: