API INTERNAL DOCUMENTATION

Discrete Visit API

Discrete Visit API returns a daily or hourly time series of Visits to a specified location on a specified date, where a Visit indicates the location of an individual agent in a particular hour or day.

This API can be used, for example, to compute footfall, which is the unique count of agents per hour in a specified location.

Connection Information

  • Version: 2
  • End Point: https://apistore.datasparkanalytics.com:8243/discretevisit/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.
discrete_visit_subzone String Dimension Subzone of the Visit, according to the Singapore GeoHierarchy.
discrete_visit_planningarea String Dimension Planning area of the Visit, according to the Singapore GeoHierarchy.
discrete_visit_planningregion String Dimension Planning region of the Visit, according to the Singapore GeoHierarchy.
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).
total_records Long Metric Total number of visits (aggregation: longSum).

Query Object

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

Property Data Type Description Mandatory
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 Object List of aggregated metrics to return, along with the aggregation function to apply. Yes
multiDayAggregations Multi-day Aggregation Object 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_records 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

Unique Footfall Count

Hourly unique footfall for People's Park Subzone on 30 May 2017.

Query

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

Result

[
 {
   "timestamp": "2017-05-30T00:00:00.000+08:00",
   "event": {
     "discrete_visit_subzone": "OTSZ02",
     "footfall": 1248
   }
 },
 {
   "timestamp": "2017-05-30T01:00:00.000+08:00",
   "event": {
     "discrete_visit_subzone": "OTSZ02",
     "footfall": 1376
   }
 },
 {
   "timestamp": "2017-05-30T02:00:00.000+08:00",
   "event": {
     "discrete_visit_subzone": "OTSZ02",
     "footfall": 1374
   }
 },
 ...
]

Unique Footfall Count with Filter and Facet

Hourly unique footfall for people born from 1980 to 2000 (inclusive), and grouped by gender in Orchard Planning Area on 30 May 2017.

Query

{
  "date": "2017-05-30",
  "location": {
    "locationType": "locationHierarchyLevel",
    "levelType": "discrete_visit_planningarea",
    "id": "OR"
  },
  "queryGranularity": {
    "type": "period",
    "period": "PT1H"
  },
  "filter": {
    "type": "bound",
    "dimension": "agent_year_of_birth",
    "lower": 1980,    "upper": 2000  },
  "dimensionFacets": [    "agent_gender"  ],
  "aggregations": [
    {
      "metric": "unique_agents",
      "type": "hyperUnique",
      "describedAs": "footfall"
    }  
 ]
}

Result

[
  {
    "timestamp": "2017-05-29T16:00:00.000Z",
    "event": {
      "agent_gender": "F",
      "discrete_visit_planningarea": "OR",
      "footfall": 1040
    }
  },
  {
    "timestamp": "2017-05-29T16:00:00.000Z",
    "event": {
      "agent_gender": "M",
      "discrete_visit_planningarea": "OR",
      "footfall": 1426    }  },
  {
    "timestamp": "2017-05-29T17:00:00.000Z",
    "event": {
      "agent_gender": "F",
      "discrete_visit_planningarea": "OR",
      "footfall": 522
    }
  },
  {
    "timestamp": "2017-05-29T17:00:00.000Z",
    "event": {
      "agent_gender": "M",
      "discrete_visit_planningarea": "OR",
      "footfall": 755
    }
  },
  ...
]

Unique and Total Footfall Count

Full day unique footfall and total visits (including repeated visits) for East Planning Region on 30 May 2017.

Query

{
  "date": "2017-05-30",
  "location": {
    "locationType": "locationHierarchyLevel",
    "levelType": "discrete_visit_planningregion",
    "id": "ER"
  },
  "queryGranularity": {
    "type": "period",    "period": "P1D"  },
  "aggregations": [
    {
      "metric": "unique_agents",
      "type": "hyperUnique",
      "describedAs": "footfall"
    },
    {
      "metric": "total_records",
      "type": "longSum",
      "describedAs": "total_visits"
    }
  ]
}

Result

[
 {
   "timestamp": "2017-05-30T00:00:00.000+08:00",
   "event": {
     "discrete_visit_planningregion": "ER",
     "total_visits": 47634708,
     "footfall": 1063233
   }
 }
]