API INTERNAL DOCUMENTATION

Stay Point API

Stay Point API indicates the location where an individual agent has stayed for at least 15 minutes. It returns daily or hourly time series of stay points to a specified location on a specified date.

This API can be used to find out the number of agents who spend time at specific locations, not just passing through the location.

Note: From 1 May 2018 onwards, Stay Point data will use the latestDiscretized Stay Point algorithm. Expect to see different graph shape during this period.

Connection Information

  • Version: 2
  • End Point: https://apistore.datasparkanalytics.com:8243/staypoint/v2/query
  • HTTP Method: POST
  • Consumes: application/json
  • Produces: application/json

Data Schema

Field Data Type Field Type Description
__time Timestamp Dimension Indicates the date and time of data recorded.
staypoint_subzone String Dimension Subzone of the stay point, according to the Singapore GeoHierarchy.
staypoint_planningarea String Dimension Planning area of the stay point, according to the Singapore GeoHierarchy.
staypoint_planningregion String Dimension Planning region of the stay point, according to the Singapore GeoHierarchy.
stay_duration Long Dimension Duration of the stay in minutes, used for filtering.
agent_year_of_birth String Dimension Agent's year of birth (four-digits). For example, 1990.
agent_gender String Dimension Agent's gender, one of M (male), F (female) or NA (unknown).
agent_race String Dimension Agent's race, one of CHINESE, EURASIAN, INDIAN, MALAY, OTHERS or NA (unknown).
agent_nationality String Dimension Agent's nationality (ISO 3-character country code). For example, SGP for Singapore, HKG for Hong Kong, AUS for Australia.
agent_home_subzone String Dimension Subzone of agent's inferred home location.
agent_home_planningarea String Dimension Planning area of agent's inferred home location.
agent_home_planningregion String Dimension Planning region of agent's inferred home location.
agent_work_subzone String Dimension Subzone of agent's inferred work location.
agent_work_planningarea String Dimension Planning area of agent's inferred work location.
agent_work_planningregion String Dimension Planning region of agent's inferred work location.
country_code String Dimension Roamer - Country code of Subscriber Identification Module (SIM).
country_name String Dimension Roamer - Country name of SIM.
unique_agents Hyperlog Metric Unique count of agents (aggregation: hyperUnique).
sum_stay_duration Long Metric Total duration of stays (aggregation: longSum).
total_stays Long Metric Total number of stays (aggregation: longSum).

Query Object

Main query object, to be passed in the body of the HTTP POST request.

Property Data Type Description Required
date Dates Object Provide information on the query period. Yes
location Location Object Provide location information for which data needs to be queried. In Singapore, this can be a single Planning Region, Planning Area, or Subzone. Yes
queryGranularity Granularity Object The time series granularity for results. Yes
filter Filter Object Filters to apply to the query. Filters can be applied to any dimensions in the data. For example, get data only for specified demographic segments. Note: When using bound filters for numeric value comparison use "ordering" field and set it to "numeric". No
dimensionFacets List of Strings List of dimensions to group results by. For example, to get a breakdown of the results by home location. No
aggregations List of Aggregation Objects List of aggregated metrics to return, along with the aggregation function to apply. Yes
multiDayAggregations Multi-day Aggregation Objects Additional multi-day aggregation metric to aggregate data from multiple dates selected. No

Response Object

The response object is a list of properties, each of which has the following properties:

Property Data Type Description
timestamp String RFC3339 date-time timestamp of the record in UTC time zone.
event Object The properties of an object depend on the query. The properties will include all dimensionFacet (group by) dimensions and aggregate metrics.

Extrapolation

Any aggregations on unique_agents and total_stays will be extrapolated from the telco observations to the population level by applying a computed extrapolation factor that is based on market share, mobile device ownership, and other factors.

Examples

Hourly Unique Agents

Hourly number of unique agents who stayed at People's Park Subzone on 29 May 2017.

Query

{
    "date": "2017-05-29", 
    "location": {
    "locationType": "locationHierarchyLevel", 
    "levelType": "staypoint_subzone",
    "id": "OTSZ02"
  },
  "queryGranularity": {
    "type": "period",
    "period": "PT1H"
  },
  "aggregations": [
    {
      "metric": "unique_agents",
      "type": "hyperUnique"
    }
  ]
}

Result

[
 {
   "timestamp": "2017-05-29T00:00:00.000+08:00",
   "event": {
     "staypoint_subzone": "OTSZ02",
     "hyperUnique_unique_agents": 909
   }
 },
 {
   "timestamp": "2017-05-29T01:00:00.000+08:00",
   "event": {
     "staypoint_subzone": "OTSZ02",
     "hyperUnique_unique_agents": 146
   }
 },
 ...
]

Hourly Unique Agents with Minimum Stay Filter

Hourly number of unique agents who stayed at Orchard Planning Area for more than 60 minutes on 29 May 2017.

Query

{
  "date": "2017-05-29",
  "location": {
    "locationType": "locationHierarchyLevel",
    "levelType": "staypoint_planningarea",
    "id": "OR"
  },
  "queryGranularity": {
    "type": "period",
    "period": "PT1H"
  },
  "filter": {
    "type": "bound",
    "dimension": "stay_duration",
    "lower": 60
  },
  "aggregations": [
    {
      "metric": "unique_agents",
      "type": "hyperUnique"
    }
  ]
}

Result

[
 {
   "timestamp": "2017-05-29T00:00:00.000+08:00",
   "event": {
     "staypoint_planningarea": "OR",
     "hyperUnique_unique_agents": 1868
   }
 },
 {
   "timestamp": "2017-05-29T01:00:00.000+08:00",
   "event": {
     "staypoint_planningarea": "OR",
     "hyperUnique_unique_agents": 200
   }
 },
 ...
]

Number of Stays and Total Duration in 4-Hour Time Bands

Number of stays and total duration in 4-hour time bands, for East Planning Region on 29 May 2017. This can be used to compute the average duration per stay (duration/stays).

Query

{
  "date": "2017-05-29",
  "location": {
    "locationType": "locationHierarchyLevel",
    "levelType": "staypoint_planningregion",
    "id": "ER"
  },
  "queryGranularity": {
    "type": "period",
    "period": "PT4H"
  },
  "aggregations": [
    {
      "metric": "sum_stay_duration",
      "type": "longSum"
    },
    {
      "metric": "total_stays",
      "type": "longSum"
    }
  ]
}

Result

[
 {
   "timestamp": "2017-05-29T00:00:00.000+08:00",
   "event": {
     "staypoint_planningregion": "ER",
     "longSum_sum_stay_duration": 344695235,
     "longSum_total_stays": 544167
   }
 },
 {
   "timestamp": "2017-05-29T04:00:00.000+08:00",
   "event": {
     "staypoint_planningregion": "ER",
     "longSum_sum_stay_duration": 56593692,
     "longSum_total_stays": 195822
   }
 },
 ...
]