API INTERNAL DOCUMENTATION

OD Matrix

OD Matrix API returns a list of origins for a specified destination or vice versa on a specified date, where an Origin-Destination pair are two consecutive Stay Points of an agent. 

This API can be used, for example, to identify the previous locations of agents who have arrived at a destination, or the next locations of agents who have left the origin. 

Connection Information

  • Version: 3
  • End Point: https://apistore.datasparkanalytics.com:8243/odmatrix/v3/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.
origin_subzone String Dimension Subzone of the origin, according to the Singapore GeoHierarchy.
origin_planningarea String Dimension Planning area of the origin, according to the Singapore GeoHierarchy.
origin_planningregion String Dimension Planning region of the origin, according to the Singapore GeoHierarchy.
destination_subzone String Dimension Subzone of the destination, according to the Singapore GeoHierarchy.
destination_planningarea String Dimension Planning area of the destination, according to the Singapore GeoHierarchy.
destination_planningregion String Dimension Planning region of the destination, according to the Singapore GeoHierarchy.
duration Long Dimension Duration of the O-D pair in seconds, used for filtering.
distance Long Dimension Distance of the O-D pair in metres, 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.
dominant_mode String Dimension Dominant mode of transport inferred in the O-D pair. For example, TRAIN, ROAD or UNKNOWN (unable to infer).
purpose String Dimension Inferred purpose of O-D pair - values returned. For example, HW, WH, HO, WO, OH, OW or NA. H denotes home. W denotes work. O denotes others. NA denotes none of the above or unable to infer.
origin_subzone_name String Dimension Complete string name of the origin subzone as defined by URA.
origin_planningarea_name String Dimension Complete string name of the origin planning area as defined by URA.
origin_planningregion_name String Dimension Complete string name of the origin planning region as defined by URA.
destination_subzone_name String Dimension Complete string name of the destination subzone as defined by URA.
destination_planningarea_name String Dimension Complete string name of the destination planning area as defined by URA.
destination_planningregion_name String Dimension Complete string name of the destination planning region as defined by URA.
agent_home_subzone_name String Dimension Complete string name of the agent’s home subzone as defined by URA.
agent_home_planningarea_name String Dimension Complete string name of the agent’s home planning area as defined by URA.
agent_home_planningregion_name String Dimension Complete string name of the agent’s home planning region as defined by URA.
agent_work_subzone_name String Dimension Complete string name of the agent’s work subzone as defined by URA.
agent_work_planningarea_name String Dimension Complete string name of the agent’s work planning area as defined by URA.
agent_work_planningregion_name String Dimension Complete string name of the agent’s work planning region as defined by URA.
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_duration Long Metric Total duration of O-D pairs (aggregation: longSum).
sum_distance Long Metric Total distance of O-D pairs (aggregation: longSum).
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 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
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 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
queryGranularity Granularity Object The time series granularity for results. Yes
timeSeriesReference String The reference timestamp for date property and time series output. The reference timestamp is either origin or destination. Origin refers to the time when the agent left the origin, while destination refers to the time when the agent arrived at the destination. 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

Number of Agents Travelling from a Certain Origin

Number of agents and their O-D pairs with Origin at People's Park Subzone on 29 May 2017.

Query

{
  "date": "2017-05-29",
  "timeSeriesReference": "origin",
  "location": {
    "locationType": "locationHierarchyLevel",
    "levelType": "origin_subzone",
    "id": "OTSZ02"
  },
  "queryGranularity": {
    "type": "period",
    "period": "P1D"
  },
  "aggregations": [
    {
      "metric": "unique_agents",
      "type": "hyperUnique"
    },
    {
      "metric": "total_records",
      "type": "longSum"
      }
  ]
}

Result

[
 {
   "timestamp": "2017-05-29T00:00:00.000+08:00",
   "event": {
     "hyperUnique_unique_agents": 8669,
     "longSum_total_records": 8793,
     "origin_subzone": "OTSZ02"
   }
 }
]

Number of Agents Travelling from a Certain Destination with Profile Filter Grouped by Origin Subzone

 Number of O-D pairs for people born from 1980 to 2000 (inclusive) grouped by Origin Subzone, where Destination was Orchard Planning Area on 29 May 2017, for every 6-hourly time band.

Query

{
  "date": "2017-05-29",
  "timeSeriesReference": "destination",
  "location": {
    "locationType": "locationHierarchyLevel",
    "levelType": "destination_planningarea",
    "id": "OR"
  },
  "queryGranularity": {
    "type": "period",
    "period": "PT6H"
  },
  "filter": {
    "type": "bound",
    "dimension": "agent_year_of_birth",
    "lower": 1980,
    "upper": 2000
  },
  "dimensionFacets": [
    "origin_subzone"
  ],
  "aggregations": [
    {
      "metric": "unique_agents",
      "type": "hyperUnique"
    }
  ]
}

Result

[
 {
   "timestamp": "2017-05-29T00:00:00.000+08:00",
   "event": {
     "hyperUnique_unique_agents": -1,
     "destination_planningarea": "OR",
     "origin_subzone": "AMSZ01"
   }
 },
 {
   "timestamp": "2017-05-29T00:00:00.000+08:00",
   "event": {
     "hyperUnique_unique_agents": -1,
     "destination_planningarea": "OR",
     "origin_subzone": "AMSZ02"
   }
 },
 ...
 {
   "timestamp": "2017-05-29T06:00:00.000+08:00",
   "event": {
     "hyperUnique_unique_agents": 100,
     "destination_planningarea": "OR",
     "origin_subzone": "AMSZ02"
   }
 },
 {
   "timestamp": "2017-05-29T06:00:00.000+08:00",
   "event": {
     "hyperUnique_unique_agents": 95,
     "destination_planningarea": "OR",
     "origin_subzone": "AMSZ03"
   }
 },
 {
   "timestamp": "2017-05-29T06:00:00.000+08:00",
   "event": {
     "hyperUnique_unique_agents": 92,
     "destination_planningarea": "OR",
     "origin_subzone": "AMSZ04"
   }
 },
 {
   "timestamp": "2017-05-29T06:00:00.000+08:00",
   "event": {
     "hyperUnique_unique_agents": 44,
     "destination_planningarea": "OR",
     "origin_subzone": "AMSZ05"
   }
 },
 {
   "timestamp": "2017-05-29T06:00:00.000+08:00",
   "event": {
     "hyperUnique_unique_agents": 66,
     "destination_planningarea": "OR",
     "origin_subzone": "AMSZ06"
   }
 },
   ...
]

Total Duration, Distance and Number of OD Pairs Grouped by Destination Filtered by Origin

Total duration, distance and number of O-D pairs grouped by Destination Planning Region, where Origin was East Planning Region on 29 May 2017. This can be used to compute the average duration per O-D pair (duration/records) or the average distance per O-D pair (distance/records).

Query

{
 "date": "2017-05-29",
 "timeSeriesReference": "origin",
 "location": {
   "locationType": "locationHierarchyLevel",
   "levelType": "origin_planningregion",
   "id": "ER"
 },
 "queryGranularity": {
   "type": "period",
   "period": "P1D"
 },
 "dimensionFacets": [
   "destination_planningregion"
 ],
 "aggregations": [
   {
     "metric": "sum_duration",
     "type": "longSum"
   },
   {
     "metric": "sum_distance",
     "type": "longSum"
   },
   {
     "metric": "total_records",
     "type": "longSum"
   }
 ]
}

Result

[
 {
   "timestamp": "2017-05-29T00:00:00.000+08:00",
   "event": {
     "longSum_sum_duration": 1085682209,
     "destination_planningregion": "CR",
     "longSum_total_records": 381629,
     "longSum_sum_distance": 6355331820,
     "origin_planningregion": "ER"
   }
 },
 {
   "timestamp": "2017-05-29T00:00:00.000+08:00",
   "event": {
     "longSum_sum_duration": 2235774346,
     "destination_planningregion": "ER",
     "longSum_total_records": 1007109,
     "longSum_sum_distance": 6181525924,
     "origin_planningregion": "ER"
   }
 },
   ...
]