{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"d8e042de-3754-42b6-beb6-a174697eddf8","name":"Telus Insights Location API","description":"[Telus Insights](https://www.youtube.com/watch?v=Mv29cjU5u_I) solution helps customers utilize TELUS Geo-intelligence data assets and help answer a range of questions around location and movement patterns within Canada.\n\nKey Highlights of TELUS Insights Location API:\n\n- Process and record over 3B location data records per day.\n- Data assets are enhanced using algorithmic logic, and data models providing meaningful location based insights\n- We have developed an advanced set of privacy and security de-identification techniques leveraging the Privacy and Security by Design Standards meaning that the data in use is completely stripped of personal information, and securely managed.\n- RESTful API’s and advanced API Gateway management means that data ingestion, integration and consumption is easy, up to date, and meets the necessary data management standards.\n- A Developer Portal that is much more than just API documentation. It is serving mulitple purposes including enabling users to explore interactively the API endpoints through a user-friendly interface. See API vs Developer Portal for more details.\n \n\n# Introduction - Generalities\n\n### Data Recency\n\n- Data is collected and processed every 5 mins from our network, and through a series of data processing jobs\n- Live data is processed, transformed, and made available within our Data Warehouse within 1-2 hours\n- Results are provided at a minimum of 15 minute intervals to ensure privacy.\n \n\n### Data Retention\n\n- Data available from January 1, 2019\n- Data will remain in the system for up to 5 years, starting from this date.\n \n\n### Coverage / Users\n\n- 9.8M Canadians, and 3M+ International devices (monthly average)\n- TELUS has network coverage in 99% of the populated areas of Canada. This means that if you are looking for information on areas where people are located, we will likely have it.\n \n\n### Data Storage\n\n- All data is stored in Canada within secure data facilities with the ability to scale to accomodate for both the massive amounts of data, and the demands of users querying the system.\n \n\n### Data Privacy\n\n- Removal of key identifiers from the dataset, replacing them with pseudonymous persistent identifiers. More on Data Privacy [here](https://www.youtube.com/watch?v=04jNbstgKlI&t).\n- All data released by the platform is aggregated so that any output is at a minimum of 20 devices post-extrapolation, and rounding. This aggregation is done across spatial and temporal dimensions.\n- All data is rounded-up to the nearest 10 counts.\n- All results are extrapolated to represent the entire population to provide a layer of privacy.\n- TELUS uses internal market intelligence and external sources to determine factors down to a census sub-division level for Canadians, and to country level for international markets.\n- TELUS has updated its privacy policy to ensure that there is enough information available to the general population on what we are doing.\n- We have sought outside expertise from a range of trusted Privacy advisors and Privacy tech companies to validate our approach\n- Achieved Privacy By Design certification\n- Close collaboration and partnership with TELUS Data & Trust Office, ensuring inclusion in any key product decisions.\n \n\n### Limitations\n\n- The API results depend on cell tower locations at the time of the analysis. As Telus is continuously optimizing its network coverage, some of the cell towers might change locations over time which might result in a slight impact on the API outputs.\n- Due to technical issues, the API will not return any results for the dates listed above as the data was not captured in our system:\n - June 14, 2021\n - June 15, 2021\n - June 16, 2021\n\n# Introduction - Spatial aggregation\n\n- TELUS Insights API data is based on the locations of Cellular towers, and their coverage areas. This means that results spatial granularity is dependent on the cellular coverage in the area. In urban areas, coverage accuracy is sub-200 meter, in suburban areas it ranges between 200m and 1km, in rural areas the coverage areas are between 1 and many kilometers, depending on the remoteness of the location.\n- In general, networks are modelled after human population and mobility behaviours. For example, towers will be aligned to all major roadways, with a tower at or between each exit. This means that we can build detailed results around travel patterns on major roads, even if the coverage in remote areas is in the several kilometer range.\n- Spatial accuracy can further be improved by using data sources that align tower locations to where devices commonly connect to the given tower. These data sets help us further align towers to roadways, improving accuracy in distinguishing between parallel road segments.\n- In some areas of Canada, the deployment of small cell technology (the precursors to 5G) allow for intersection level accuracy within neighbourhoods. This technology requires for small cell sites to be deployed on existing infrastructure, such as light standards, traffic signals, or phone line poles. This significantly increases the resolution spatially of the data, into the 5-10m range.\n- TELUS Insights data has the ability to aggregate results to customer specified areas, or road segments, because the data is collected based on tower location. Overall this means that the work of correlating tower locations to customer specified areas is complete by TELUS Insights.\n \n\n# Introduction - Methodologies\n\n## Assumed Primary and Secondary neighbourhoods methodology\n\nTELUS Insights has developed a proprietary algorithm to determine the primary and secondary neighbourhood of the devices. This algorithm looks at a series of factors, such as time spent in an area, number of days spent, frequency of visits, consecutive hours, and others, to decide the primary and secondary neighbourhoods of a device. This algorithm is designed to ensure the model works in a broad range of conditions, including rural, and urban areas.\n\nThe algorithm has been built in a way that the secondary neighbourhood is not confused with primary neighbourhood.​\n\n## Extrapolation methodology\n\nTo be fully representative of the Canadian population, TELUS Insights extrapolates the subscriber data based on our market share information. TELUS builds highly detailed market shares, broken down by census sub-divisions. These market shares account for many variables, including the likelihood of an individual owning multiple devices, the drop off points of access to cellular service, as well as area populations. Each device is given a multiplier to help it be representative of its home neighbourhood at a census sub-division level.\n\n# Introduction - Insights Developer Portal\n\n[Insights Developer Portal](https://insights.telus.com/) enables the users to explore, interact and query the API through an intuitive interface.\n\nDevoloper Portal provides self-serve capabilities on top of the API such as:\n\n- API Documentation\n- API credentials\n- Support desk\n- Product notifications\n- More to come\n \n\n### Insights Developer Portal Homepage\n\n\n\n# Introduction - API Integrations\n\n​ \nIn order to build automated solutions for API consumption, we recommend the following process and best practices\n\n## 1\\. OAuth Credentials\n\nRequest OAuth credentials by creating a ticket in the Portal. Check your My Account page in the portal to determine if you already have them.\n\n## 2\\. Creating Script Snippets\n\nTo create scripts for your favorite language you can get some code snippets from the “Example Request” section for each API on this site.\n\n\n\n\n\n``` bash\n# Set your credentials - Check My Account Page\ncustomerId=\"\"\noauth_client_id=\"\"\noauth_client_secret=\"\"\n# OAuth config - Check My Account Page\noauth_token_endpoint=\"\"\noauth_grant_type=\"\"\noauth_scope=\"\"\nlocation_api_url=\"\"\n# Set thresholds\nwaitSecondsBeforeFetchingJobResults=300s\n# Set your request body variables. You can use the JSON preview feature in the Portal to get this info.\ninputRequestId=\"your-input-request-id\"\ninputStudyZones='\"studyzone-1\",\"studyzone-2\"'\noutputRequestId=\"your-input-output-id\"\noutputStudyZones='\"studyzone-1\",\"studyzone-2\"'\nstartTime=\"2020-10-04T00:00:00\"\nendTime=\"2020-10-06T00:00:00\"\n# See Swagger file for info on api request body\napi_path=\"home\"\napi_request_body='{\"input_geoid\": {\"requestId\": \"'${inputRequestId}'\",\"study_zone\": ['${inputStudyZones}']},\"output_geoid\": {\"requestId\": \"'${outputRequestId}'\",\"study_zone\": ['${outputStudyZones}']},\"start_time\": \"'$startTime'\",\"end_time\": \"'$endTime'\",\"time_bucket_size\": 15,\"exclusion_types\": []}'\n# Get access_token \naccess_token_expiry_time=`date`\ncurrent_date_time=`date`\necho \"Getting access token - current_date_time=$current_date_time\"\naccess_token_data=$(curl --request POST \\\n --url \"${oauth_token_endpoint}\" \\\n --header \"content-type: application/x-www-form-urlencoded\" \\\n --data grant_type=${oauth_grant_type} \\\n --data client_id=\"${oauth_client_id}\" \\\n --data client_secret=\"${oauth_client_secret}\" \\\n --data scope=\"${oauth_scope}\")\naccess_token=$(echo $access_token_data | jq --raw-output .access_token)\naccess_token_expiry_in_seconds=$(echo $access_token_data | jq --raw-output .expires_in)\naccess_token_expiry_time=$(date --date=\"+$(expr $access_token_expiry_in_seconds - 5) seconds\")\necho \"Authorization: Bearer ${access_token}\"\n# POST a Job\njobStartTime=`date \"+%Y-%m-%d %H:%M:%S\"`\njobData=$(curl --request POST \\\n --url \"${location_api_url}/count/${api_path}\" \\\n --header \"content-type: application/json\" \\\n --header \"Authorization: Bearer ${access_token}\" \\\n --header \"customerid: ${customerId}\" \\\n --data \"${api_request_body}\")\n# Retrive the Job Id\necho \"jobData=${jobData}\"\njobId=$(echo $jobData | jq --raw-output .jobId)\necho \"jobId=$jobId\"\n# Check Job Results in a loop\necho \"Starting the GET loop for a job.........\"\nstatus=\"not-done\"\nwhile [ $status != \"COMPLETE\" ]\ndo\n echo \"sleeping for $waitSecondsBeforeFetchingJobResults .... \"\n sleep $waitSecondsBeforeFetchingJobResults\n echo \"checking job status .... \"\n # Refresh access_token if its expiry time is in the past\n current_date_time=`date`\n if [[ $(date +%s -d\"$access_token_expiry_time\") -le $(date +%s -d\"$current_date_time\") ]]\n then \n echo \"Getting access token - access_token_expiry_time=$access_token_expiry_time, current_date_time=$current_date_time\"\n access_token_data=$(curl --request POST \\\n --url \"${oauth_token_endpoint}\" \\\n --header \"content-type: application/x-www-form-urlencoded\" \\\n --data grant_type=${oauth_grant_type} \\\n --data client_id=\"${oauth_client_id}\" \\\n --data client_secret=\"${oauth_client_secret}\" \\\n --data scope=\"${oauth_scope}\")\n access_token=$(echo $access_token_data | jq --raw-output .access_token)\n access_token_expiry_in_seconds=$(echo $access_token_data | jq --raw-output .expires_in)\n access_token_expiry_time=$(date --date=\"+$(expr $access_token_expiry_in_seconds - 5) seconds\")\n # echo \"Authorization: Bearer ${access_token}\"\n fi\n results=$(curl --request GET \\\n --url \"${location_api_url}/count/${api_path}/${jobId}\" \\\n --header \"Authorization: Bearer ${access_token}\" \\\n --header \"customerid: ${customerId}\")\n # Check job status\n # echo \"results=${results}\"\n status=$(echo $results | jq --raw-output .status)\n if [[ $status != \"COMPLETE\" ]]\n then \n echo \"Not complete yet, will poll again ...\"\n else\n jobEndTime=`date \"+%Y-%m-%d %H:%M:%S\"`\n echo \"Results received ...............\"\n echo \"status=$status. Job results saved to ${jobId}.json\"\n echo \"Total time taken=$(expr $(date -d \"$jobEndTime\" \"+%s\") - $(date -d \"$jobStartTime\" \"+%s\")) seconds\"\n echo \"$results\" >> ${api_path}.${jobId}.json\n fi\ndone\n\n```\n\n# Introduction - API Restrictions and Usage\n\n## API Restrictions\n\nCurrently Rate-limiting is not implemented for the API. However, in order to ensure the API performance and stability, it is strongly recommended that all users follow the below limitations:\n\n### 1 Day Queries\n\nMinimum Time Bucket Size of 15 min is allowed for queries ranging up to 1 day period\n\n### 30 Day Queries\n\nMinimum Time Bucket Size of 60 min is allowed only for queries ranging up to 30 days period\n\n### More than 30 Day Queries\n\nMinimum Time Bucket Size of 24 Hrs is allowed for queries more than 30 days\n\n### Concurrent Queries\n\nOnly run 5 concurrent queries at a time. This includes queries submitted via the API and the portal.\n\n### Query Volume\n\nOnly run 10 queries per hour and 100 queries per day\n\n## Usage Statistics\n\nWe have now made available the usage statistics at an organization level to help you understand the overall API consumption. This feature primarily provides the following:\n\n- Number of monthly API Calls\n- Number of Study Zones queried\n \n\nThis will enable you to understand and administer your organization's usage against the plan's limit.\n\n'Usage Statistics' option has been made available under 'Account Settings' as depicted below:\n\n\n\nBy default, the statistics will be displayed for the current month and year which could be changed using the dropdowns.\n\nThere are three parts to Usage Statistics.\n\n**Part 1:** Primary information i.e. number of monthly API Calls and number of Study Zones queried for the selected month and year as depicted below:\n\n\n\n**Part 2:** End-point wise breakdown of the total API Calls based on the selected month and year as depicted below:\n\n\n\n**Part 3:** Comparison of total no. of API Calls and Study Zones queried in the current year (based on selection) and the previous year as depicted below:\n\n\n\n## Best Practices\n\n### Query Processing Time\n\nThe processing time is proportional to the complexity of the query and the volume of the data being fetched. In order to reduce the processing time, it is highly recommended to break down your queries for smaller date ranges.\n\n### OAuth Token\n\nWhen getting an OAuth Token from the Token URL, it is preferable that you reuse the token for specified amount of expiry seconds (present inside the token JSON and set to 299 seconds). That prevents the identity system from being overwhelmed.\n\n### Wait Time before results\n\nThe API is asynchronous, when a POST is submitted to start a job, a Job Id is returned. The job results can be fetched by doing a GET using the Job Id. It is recommended to wait a minimum of 5 minutes before submitting a GET for the results. Because the job results are not guaranteed within 5 minutes, we recommend that you create a loop to check the results based on the “status” field equal to “COMPLETE” that you get back in the API response.\n\n### Volume of Queries\n\nTo protect our platform from overload, we recommend users not to exceed 10 queries on average per hour and 100 queries per day. Please note that these are averages for full POST and GET cycle of the request. This means that it is OK for you to submit (POST) 10 queries within a minute and then wait for them to complete (GET) within an hour.\n\n# Getting Started\n\nWe are invested in your success and wrote this guide to help you get started in the quickest and most optimal manner. This quick Start Guide will help you analyze your first study zone and unlock your first insights. Specifically, it will cover:\n\n1. Authentication\n2. Upload Shapefile\n3. Run a job\n4. Data Dictionary and Formats\n5. Exclusion Types\n6. API Function Descriptions\n \n\n# Getting Started - Authentication\n\n## Telus Insights Portal\n\nAuthentication to Telus Insights Portal ([https://insights.telus.com](https://insights.telus.com)) will be done through Telus Client Identity. Two emails will be sent as a part of the onboarding process – first will be an informative email (from [dlTelusInsights@telus.com](mailto:dlTelusInsights@telus.com)) containing links to the Telus Insights Portal and our API Documentation and the other will be an activation/registration email through our Telus Client Identity system ([do.not.reply@telus.com](mailto:do.not.reply@telus.com)) that would allow you to create a password. The user ID is the email address.\n\nNote: If you are already registered with Telus Client Identity, you could start accessing Telus Insights Portal once you receive the informative email from [dlTelusInsights@telus.com](mailto:dlTelusInsights@telus.com).\n\n## API\n\nTo authenticate to the API - [https://location-api.insights.telus.com](https://location-api.insights.telus.com), please refer to OAuth credentials (Client Id and Secret) and the configuration details on your 'My Account' page in Telus Insights Portal. More details could be found on the [API Integrations page](https://docs.insights.telus.com/#introduction-api-integrations).\n\n# Getting Started - Shapefiles and Study Zones\n\nA study zone is a location, or set of locations defined as a geospatial boundary otherwise known as a “Geo Fence” that defines an area such as a Mall, an FSA, FSA-LDU or Census boundary.\n\nBefore making a POST/GET request to the Count endpoint, areas of study needs to be defined. The areas of study are a list of “Study Zones” (aka polygons) defined within the shapefile. Each Study Zone will have a series of latitude and longitudes associated with the Study Zone.\n\nEach study area will be defined, uploaded and maintained in the system as a set of Latitude Longitude that encapsulate a geo fence.\n\nBefore a user can query the Count endpoint, a study zone must be defined which includes a location, or group of locations you would like to include in analysis.\n\nYou could either create your own **Custom Shapefile** using our shapefile endpoint or use one of the **Public Shapefiles** downloaded from [Stats Canada website](https://www.statcan.gc.ca/en/geography?MM=1) made available to you for your analysis.\n\n## Public Shapefiles\n\n**Public shapefiles** are geo-spatial files that store standard areas defined by public Canadian authorities such as Census Subdivision (CSD) and Forward Sortation Areas (FSA).\n\n**Source of the files:** [Stats Canada website](https://www.statcan.gc.ca/en/geography?MM=1)\n\n**Type of files:** Digital Boundary Files\n\n**Naming convention for shapefiles and study zones:** \nOriginal shapefiles have been broken down into Provincial files. For uniformity, shapefile and study zone name length will follow the same length requirements for custom shapefiles/study zones i.e. shapefile name will be <= 75 characters and study zone name length will be <= 50 characters. \nFollowing is the file and shapefile naming conventions:\n\n**CSD files:**\n\n```\npublic_canada_csd_CensusYear_PRCode_PRUID.zip\n\n```\n\nCensus Year is the year for which file is available, PR Code is the province/territory code and PRUID is the unique identifier for each province/territory.\n\n```\nExample shapefile name: public_canada_csd_2021_bc_59.zip\nExample RequestID: public-canada-csd-2021-bc-59-zip-{random GUID}\n\n```\n\nFor study zones, naming convention is 'CSD Name' followed by 'CSD Type'. There are about 50 CSDs which have duplicate CSD Name and Type combination; to uniquely identify these CSDs in the system, 'DGUID' has been appended into the study zone name.\n\n```\nExample without DGUID: Victoria(CY)\nExample with DGUID: Okanagan (Part) 1(IRI)(5937801)\n\n```\n\nReferences: [Dictionary, Census of Population, 2021](https://www12.statcan.gc.ca/census-recensement/2021/ref/dict/az/index-eng.cfm)\n\n**FSA files:**\n\n```\npublic_canada_fsa_CensusYear_PRCode_PRUID.zip\n\n```\n\nCensus Year is the year for which file is available, PR Code is the province/territory code and PRUID is the unique identifier for each province/territory.\n\n```\nExample shapefile name: public_canada_fsa_2021_bc_59.zip\nExample RequestID: public-canada-fsa-2021-bc-59-zip-{random GUID}\n\n```\n\nFor study zones, CFSAUID which uniquely identifies a forward sortation area composed of three alphanumeric characters.\n\n```\nExample: V3T\n\n```\n\nReferences: [Forward Sortation Area, Boundary File, Reference Guide](https://www150.statcan.gc.ca/n1/pub/92-179-g/2011001/tech-eng.htm)\n\n**Release dates:**\n\nCSD Files: 2021\n\nFSA Files: 2021\n\n**How to use Public Shapefiles:** \nPublic Shapefiles are made available on the Job Tool screen below the Custom Shapefiles under Shapefile/RequestID drop-down list as depicted below.\n\n\n\nGeofence endpoint will also return the list of Public Shapfile Request IDs below the Custom Shapefile Request IDs list.\n\n**Future Changes:** A separate section under 'Study Zone Management' in the Portal to view details of Public Shapefiles.\n\n## Uploading a shapefile / preparing your Study Zones\n\nThis section explains the process of uploading custom shapefiles.\n\nThe system supports multiple formats including Google’s KML (Keyhole Markup Language), ESRI Shapefiles and GeoJson.\n\nOur shapefile endpoint allows you to do the following:\n\n- Upload your own unique shapefiles and polygons (study zones/areas)\n- Polygons could be anything including but not limited to:\n - Province\n - City\n - Region\n - Postal codes\n- Shapefile information including study zone names are stored for future use\n- This information is stored in our application database for fast processing\n \n\nOnce the shapefile has been accepted by the system, it will return a `requestID`. This `requestID`, once processed, along with the Study Zone names will be what you use to make the calls to the Count endpoints.\n\n### Shapefile format requirements\n\n| Requirements | Details |\n| --- | --- |\n| Format | .kml (Google Keyhole Markup)
.zip (ESRI Shapefile)
.json |\n| Formats in ZIP file | .dbf, .prj, .shp, .shx, .cpg |\n| Max File Size | 25 MB |\n| Max Row Size for Study Zone | 4 MB |\n| Column Names | Add 'study_zone' column and list out all relevant polygon coordinates |\n| Max no. of Study Zones | 2000 |\n| File name length | 75 characters |\n| Study Zone name length | 50 characters |\n| Study Zone name | 1\\. Must be unique
2\\. Must NOT contain backslashes or quotation marks
3\\. Cannot be changed after upload |\n| Polygon Coordinates | Our system only handles flat geometries i.e. the coordinates must be two dimensional
Sample coordinates: -100.0000000, 50.0000000
If the shapefile contains a third dimension (Z), the same will be ignored and only the X and Y coordinates will be stored for processing.
Sample coordinates with third dimension: -100.0000000, 50.0000000, 2
Coordinates stored for processing: -100.0000000, 50.0000000 |\n\n\n\n\n\n# Getting Started - Run a job\n\nWe can run a job through below two options:\n\n- **Insights Developer Portal**\n- **Rest API**\n \n\n## Insights Developer Portal\n\nInsights Developer Portal have the ability to test, explore all the API endpoints through Insights Developer Portal, by selecting a job type in Data Job tool.\n\n\n\nYou can also edit an existing job and re-run it from View Data Jobs screen.\n\n## Rest API\n\n### Asynchronous Computation\n\n- When a request is submitted, the client application makes a synchronous call to the API, triggering a long-running operation on the backend on the order of seconds or minutes.\n- API responds synchronously as quickly as possible. It returns an HTTP 202 (Accepted) status code, acknowledging that the request has been received for processing.\n- API validates both the request and the action to be performed before starting the long running process. If the request is invalid, API will reply immediately with an error code such as HTTP 400 (Bad Request).\n- While the request is still pending, the status endpoint returns HTTP 202 status code and request status as \"Processing\". Once the request is complete, the status endpoint will return required results which indicates completion of request.\n \n\n\n\n## Job Queues\n\nWe use a two part POST and GET method when making a call to our Endpoints. The POST request will validate the request and return a job ID, which should then be used to obtain the results via the GET request.\n\nQueries are processed based on available computation space.\n\nMost of the time, your results will be available on your first `GET` call. If it is not, it could be because your request is very large, or the server is busy. In this case, you may need to check the status of your request more than once. As a best practice, retry `GET` every 5 minutes.\n\nThe schema below shows a typical workflow for a study using the Location API. First, you will post your postRequest. Then you will post your getRequest to retrieve the status of your task.\n\n## HTTPS POST request\n\nThe data processing from the API calls are computed asynchronously. This means that you won't get the results of your call immediately. You will be returned a JobID, which represents the request you have made for the system.\n\n``` json\n{\n \"jobId\": \"84f4a1ba-a0d7-41d8-bc09-944440da6476\",\n \"link\": {\n \"rel\": \"dwelltime\",\n \"url\": \"/count/dwelltime/84f4a1ba-a0d7-41d8-bc09-944440da6476\"\n }\n}\n\n```\n\nThere are multiple ways to POST a request to a REST API.\n\n**Best Practices:**\n\n- Use an extension for your browser such as:\n - Chrome: Postman, Advanced REST Client\n - Firefox: REST Easy, RESTClient\n- As a POST method, parameters of the request are not directly included in the URL. You need to attach them to your request.\n- The parameters/arguments are always in JSON format, with the returned response always in JSON.\n- The specific parameters depend on the API function you want to call.\n - The JSON response can be converted easily to CSV / excel using a variety of tools from the internet.\n\nTo find more information on what arguments to pass, please refer to the [API's Reference section](https://docs.insights.telus.com/#count-apis-reference-section)\n\n## HTTPS GET request\n\nTo get the status of your POST request, you need to send a request to the corresponding getRequest method using JobID generated during POST request for the respective API endpoint.\n\n- After GET request is submitted, if the computation is completed, this method will return the results similar to below results.\n \n\n``` json\n{\n \"requestId\": \"51a11295-2a94-40ac-82e5-29161faf9000\",\n \"study_zones\": [\n {\n \"geoid\": \"Kelowna\",\n \"buckets\": [\n {\n \"bucket\": \"2019-01-01T00:00:00\",\n \"0-15\": 35900\n }\n ]\n }\n ],\n \"bucket_size\": 1440,\n \"start_time\": \"2019-01-01T00:00:00\",\n \"end_time\": \"2019-01-02T00:00:00\"\n}\n\n```\n\n- Otherwise it will return a status of PROCESSING until request is completed.\n \n\n``` json\n{\n \"jobId\": \"84f4a1ba-a0d7-41d8-bc09-944440da6476\",\n \"status\": \"Processing\",\n \"link\": {\n \"rel\": \"dwelltime\",\n \"url\": \"/count/dwelltime/84f4a1ba-a0d7-41d8-bc09-944440da6476\"\n }\n}\n\n```\n\n# Getting Started - Data Dictionary and Formats\n\n| Data Attribute | Data Type | Format | Min / Max Values | Description |\n| --- | --- | --- | --- | --- |\n| `dwell_time_bucket` | Integer | 0 | Min = 0
Max = no max | Specifically for the Dwell time API. This is to group count based on dwell time for each study zone. This is value in minutes. For e.g. when dwell_time_bucket is set to 60, output will contain dwell time bukcets as 0-60, 61-120, 121-180 |\n| `time_bucket_size` | Integer | 0 | Min = 0, Max=no max | Bucket size defines the number of minutes the result will be broken down into. For example 30 would mean the bucket time increment size is 30 minute aggregates or 1440 would mean the data is aggregated by day. Bucket size does not have a minimum or max limit, except for Demographic endpoint which has 1440 as a minimum value. By not selecting bucket size, it will return a collective number for the entire time period specified within the start to end date period. |\n| `timeframe_bucket` | Integer | 0 | Min = 0, Max=no max | Timeframe bucket defines the timeframe ie date of each bucket. For example 2020-10-04T13:15:00:00. |\n| timezone | String | UTC | | Timezone for request. Valid values are UTC, AST, CST, EST, PST, MST and NST. Default is UTC |\n| `start_time` | String | 2020-01-03T00:00:00 | Min=2019-01-01T00:00:00, Max=present day | Start time for request. We use the ISO8601 format for all our start and end times. |\n| `end_time` | String | 2020-01-03T01:00:00 | Min=2019-01-01T00:00:00, Max=present day | End time for request |\n| `job_id` | Alpha-numeric | 84f4a1ba-a0d7-41d8-bc09-944440da6476 | | Unique identifier generated when a POST request is made via the query end points |\n| `customer_id` | Alpha-numeric | 84f5f015-658e-4f9b-829e-a8b9c89324b4 | | This is the unique ID generated when \"Create Customer ID\" is performed which creates the association of a customer with their unique API key. |\n| `request_id` | Alpha-numeric | 51a11295-2a94-40ac-82e5-29161faf9000 | | This is the unique ID generated for each shapefile that has been uploaded |\n| `study_zone` | String | Toronto | | This is the name/label of the study area (polygon) defined based on the shapefile upload. For example, your study zone could be a city, province, or even a POI like \"Roger's Centre\" |\n| `exclusion_type` | Array | Worker | | This is further segmenting the type of individuals who are within that particular area. We have the following types: Resident, Non-Resident, Worker, Non-Worker. You cannot select Resident / Non-resident together, or Worker / Non-Worker together. |\n| `min_dwell_time` | Integer | 0 | Min = 15, Max=no max | This is the minimum time threshold (in minutes) for a user to have dwelled within the location. The time window between Min and Max Dwell must be a greater than 15 minutes |\n| `max_dwell_time` | Integer | 0 | Min = 15, Max=no max | This is the max time threshold (in minutes) for a user to have dwelled within the location. The time window between Min and Max Dwell must be greater than 15 minutes. |\n| | | | | |\n| `input_geoid` | Alpha-numeric | 2c7f6019-91a0-41e3-8e57-3250447bd902.Downtown | | This is to specify the query we are doing on a particular location. This is made up of a request ID, and one or more study zones. |\n| `output_geoid` | String | Kelowna | | Output is used when we want to break down the input of a particular study zone, which has been specified as a part of input_geoid.
For example Input could be Toronto, and the outputs could be broken down by suburb, ie Annex, Liberty Village, Ossington etc. |\n| `geoid` | String | Vancouver | | This is the names of each of the study zones (polygons) that have been uploaded via the shapefiles. This could be province names, city names, regions, postcodes (these are all mapped to a series of latitudes/longitudes). Geo-ID is the same as Study Zone, however it is the name used on the GET return as opposed with Study Zone which is used on the POST request. |\n| `topic` | String | Hindi | | The topics are a list of demographics that can be selected as part of the input parameters within the Demographic endpoint. |\n| `primary_threshold` | Decimal | 0.5 | Min = 0, Max = 1 | is a value between 0 and 1 and set the bounds at which the equation will separate out the primary, secondary and tertiary zones. |\n| `secondary_threshold` | Decimal | 0.5 | Min = 0, Max = 1 | is a value between 0 and 1 and set the bounds at which the equation will separate out the secondary and tertiary zones. |\n| `count_weight` | Decimal | 0.4 | Min = 0, Max = 1 | A value between 0 and 1 that represents how important the unique count from the given output should be in selecting if the area is a primary, secondary or tertiary area. |\n| `trip_weight` | Decimal | 0.4 | Min = 0, Max = 1 | A value between 0 and 1 that represents how important the total trips from the given output should be in selecting if the area is a primary, secondary or tertiary area. |\n| `distance_weight` | Decimal | 0.4 | Min = 0, Max = 1 | A value between 0 and 1 that represents how important the distance from the given output should be in selecting if the area is a primary, secondary or tertiary area. |\n| `cross_zone_analysis` | Boolean | true/false | | 'Cross-zone Analysis' will return the count of devices that visited all of the selected study zones. It is suggested to not break down results using time bucket size while conducting cross-zone analysis. Default value is `false`
|\n| `pass_through_geoid` | Object | `\"pass_through_geoid\": { \"requestId\": \"4693-89d5-1683d2774704\", \"study_zone\": [\"Seven Oaks\"] },` | | Specifically for Origin and Destination end-points. With pass-through study zone(s) selected, these end-points will return the counts of devices which travelled from Origin to Destination via the study zone(s) selected under pass-through geo-id. |\n\n# Getting Started - Exclusion Types\n\nExclusion types are ways to segment the query down further to exclude / include certain types of devices based on segmentation such as demographic, identity, or other defined categories.\n\n| Exclusion | Description |\n| --- | --- |\n| residents | A device who's assumed Primary neighbourhood falls under the defined study zone. |\n| non-residents | A device who's assumed Primary neighbourhood falls outside of the defined study zone. |\n| workers | A device who's assumed Secondary neighbourhood falls under the defined study zone. |\n| non-workers | A device who's assumed Secondary neighbourhood falls outside of the defined study zone. |\n\n# API Descriptions\n\n## Shapefile (Study Zone Management)\n\n| Endpoint | Description |\n| --- | --- |\n| Create New Area (upload a shapefile) | Please refer to 'Uploading a shapefile / preparing your Study Zones' section under 'Getting Started - Shapefiles and Study Zones' |\n| Status (retreive status of the shapefile) | Check the status of the shapefile, to ensure it has been processed sucessfully |\n| Geofence report | See a list of uploaded shapefiles.
This report will also include the list of public shapefiles appended below the list of custom shapefiles uploaded by that user. |\n\n## Count\n\n| Name | Description | Example |\n| --- | --- | --- |\n| Unique | Returns the number of unique devices available in the input study zone based on the input parameters. | How many unique devices visited Vancouver on May 1, 2022 between 9 AM and 1 PM. |\n| Origin | Returns the count of devices with trips origination from each output study zone (origin) and terminating to each input study zone (destination) as specified by the input parameters. | How many devices traveled from Vancouver (Origin) to Burnaby (Destination) on 1st May, 2022 between 9 AM and 1 PM. |\n| Destination | Returns the count of devices with trips origination from each input study zone (origin) and terminating to each output study zone (destination) as specified by the input parameters. | How many devices traveled from Vancouver (Origin) to Burnaby (Detination) on 1st May, 2022 between 9 AM and 1 PM. |\n| OD Matrix | OD Matrix end-point performs travel analysis (people movement analysis) between two or more study areas. It returns the count of devices that traveled along with the total no. of trips between the matrix (select study zones/areas) as specified by the input parameters. | No. of devices traveled from Vancouver (Origin) to Burnaby (Destination) and vice versa i.e. no. of devices that traveled from Burnaby (Origin) to Vancouver (Destination) along with the toal no. of trips on April 10, 2022 between 9 AM and 1 PM. |\n| Dwell Time | Returns the unqiue number of devices available based on their dwell times in the input study zone as specified by the input parameters. | How many devices spent between 30 to 90 minutes in Vancouver on May 1, 2022 between 9 AM and 1 PM. |\n| Total Trips | Returns the total number of trips made by devices to a study zone over a give period of time based on the input parameters. | How many trips did devices take to Vancouver on April 1, 2022 between 9 AM and 1 PM. |\n| Work | Returns the count of devices available in each input study zone broken-down by their corresponding assumed Work neighbourhood (output study zone) as specified by the input parameters. | How many devices were at Burnaby (visiting location) on May 1, 2022 between 9 AM and 1 PM whose assumed Work neighbourhood was Vancouver. |\n| Home | Returns the counts of devices available in each input study zone broken-down by their corresponding assumed Home Location (output study zone) as specified by the input parameters. | How many devices were at Burnaby (visting location) on May 1, 2022 between 9 AM and 1 PM whose assumed Home Location was Vancouver. |\n| Demographic | Provides the probalistic demographic breakdown based on the census data of the assumed Home Location of the devices that were available in the study zone specified under \"input geo-id\" and the input parameters. | What is the age range wise percentage of people available in Vancouver on May 1, 2022 between 9 AM and 2 PM. |\n| Repeat Visitation | Returns the number of unique devices available in the study zone more than once as specified by the input parameters. | How many devices went to Vancouver on May 1, 2022 more than once between 9 AM and 1 PM. |\n| Trade Area | Returns for each study zone selected in \"output geo-id\", a list of classification (Primary/Secondary/Tertiary) for the study zone selected in \"input geo-id\". | What would the trade category of Vancouver and Abbotsford for business in Surrey. |\n\n# API Descriptions - Destination\n\n### Description\n\nDestination end-point returns the count of devices with trips originating from each input study zone and terminating to each output study zone as specified by the input parameters.\n\nStudy zone specified within the “input geo-id” is considered to be the Origin whereas the study zone specified within the “output geo-id” is considered to be the Destination.\n\nFor a device to be qualified in the output, the trip must start (originate) and end (terminate) between the specified start and end times.\n\n### Pass-through\n\nIn addition to the above, Destination end-point also provides an option to select pass-through study zones.\n\nWith pass-through study zone(s) selected, Destination end-point will return the count of devices with trips originating from the study zone selected under input geo-id, passing through the study zones(s) selected pass-through geo-id and terminating to study zone selected under output geo-id.\n\nIn case of multiple study zones selected under pass-through, the sequence of the trip will be determined based on the order in which the pass-through study zones have been selected.\n\nConsider a scenarion wherein two study zones 'A' and 'B' have been selected under pass-through geo-id. The output would only contain the count of devices which travelled from Origin->A->B->Destination. Devices travelling through an alterate route from Origin to Destination for e.g., Origin->A->Destination or Origin->B->Destination or Origin->B->A->Destination will not be included in the output.\n\n### Example\n\nHow many devices travelled from Vancouver (Origin) to Burnaby (Destination) on May 1, 2022 between 9 AM and 1 PM.\n\nHow many devices travelled from Vancouver (Origin) to Surrey (Destination) via Burnaby (Pass-through) on May 1, 2022 between 9 AM and 1 PM.\n\n### Dwell Time\n\nMinimum and Maximum Dwell Times can be specified independently for study zones within each group i.e. Origin, Destination and Pass-through study zones or can be specified globally which will be applied to all the study zones across all groups.\n\nConsider a device traveling from Vancouver to Burnaby dwelled for 30 minutes in Vancouver as well as Burnaby.\n\nIn this case, if the Minimum Dwell Time is set to anything in excess of 30 minutes, this device will be excluded from the output; similarly, if the Maximum Dwell Time is set to anything less than 30 minutes will also exclude this device from the output.\n\n### Exclusions\n\nExclusion Types selected will remove the devices from the study area considered to the Destination.\n\nConsider a resident device of Vancouver who traveled from Vancouver to Burnaby during the specified study period. In this case, excluding ‘Residents’ will exclude the device from the output.\n\n### Bucketing\n\nDevices are bucketed based on when the trip originated from the study area considered to be the Origin.\n\nConsider a case wherein the Start Time and End Time are specified as 9 AM and 1 PM respectively, and the Time Bucket Size is set to 120 minutes; output will be comprised of two buckets: Bucket 1 from 9 AM to 11 AM and Bucket 2 from 11 AM to 1 PM. Device traveling from Vancouver to Burnaby started from Vancouver at 10:30 AM reached Burnaby at 12:30 PM.\n\nIn this case, the device will be forming a part of output under Bucket 1.\n\n# API Descriptions - Demographic\n\n### Description\n\nDemographic end-point provides the probabilistic demographic breakdown based on the census data of the Home Location of the devices that were available in the study zone specified under “input geo-id” and the input parameters.\n\n## Topics\n\nFollowing are the topics available within the Demographic end-point which could be selected as an input parameter:\n\n| Topic | Examples Characteristic | Example Value |\n| --- | --- | --- |\n| Marital Status | Married
Divorced
Living Common Law | 45%
35%
20% |\n| Age characteristics | 20 to 24 years
35 to 39 years | 10%
25% |\n| First official language spoken | English
French | 50%
35% |\n| Family characteristics - Family size | 2 persons
3 persons | 45%
35% |\n| Household and dwelling characteristics - Household size | Apartment
Detached house
Semi-detached house | 42%
16%
26% |\n| Income of households in 2015 - Household total income groups in 2015 for private households | $10,000 to $14,999
$50,000 to $59,999 | 12%
44% |\n| | | |\n\n### Example\n\nWhat is the age range wise percentage of people available in Vancouver on May 01, 2022 between 9 AM and 2 PM.\n\n# API Descriptions - Dwell Time\n\nDwell Time end-point returns the unique number of devices available based on their dwell times in the input study zone as specified by the input parameters.\n\nSimilar to Unique end-point, Dwell Time end-point analyzes each zone independently and hence contains only \"input geo-id\" as an input.\n\n### Example\n\nHow many devices spent between 30 to 90 minutes in Vancouver on May 1, 2022 between 9 AM and 1 PM.\n\n### Dwell Time\n\nMinimum and Maximum Dwell Times are applied to the study zone specified under \"input geo-id\".\n\nNote: Specifying Maximum Dwell Time is mandatory for Dwell Time end-point.\n\nConsider a device was available at Vancouver for 40 minutes during the specified study period.\n\nIn this case, if the Minimum Dwell Time is set to anything in excess of 40 minutes irrespective of the Maximum Dwell Time specified, the device will be excluded from the output; similarly, if the Maximum Dwell Time is set to anything less than 40 minutes, this device will be excluded from the output.\n\nDwell Time is calculated for each independent event and not cumulated for a device based on study period. Consider a case wherein device was available twice at Vancouver; initially from 9:00 AM to 9:30 AM (dwell time of 30 minutes) and then again from 12:15 to 1:05 PM (dwell time 50 minutes). Both these occurrences are considered to be two independent events.\n\nIn this case, if the Maximum Dwell Time is set to 40 minutes, this device will be forming a part of the output due to the first event from 9 AM to 9:30 AM. In the second query, if the Minimum Dwell Time is set to 40 minutes and Maximum Dwell Time is set to 60 minutes, the same device will again be forming a part of the output, this time due to the second event from 12:15 PM to 1:05 PM.\n\nIf the Minimum Dwell Time is set to 30 minutes and the Maximum Dwell Time is set to 60 minutes, there's a probability wherein both these events will be forming a part of the output which is further explained under Dwell Time Bucketing below.\n\n### Dwell Time Bucketing\n\nDwell Time Bucket Size will bucket the devices based on their dwell times.\n\nNote: Specifying Dwell Time Bucket Size is mandatory for Dwell Time end-point and the value cannot be more than the Maximum Dwell Time.\n\nConsider a case wherein the Start Time and End Time are specified as 9 AM and 1 PM respectively, Minimum and Maximum Dwell Times are specified as 30 and 60 respectively and the Dwell Time Bucket is specified as 15; output will be comprised of two dwell buckets: Dwell Time Bucket 1 from 30 minutes to 45 minutes and Dwell Time Bucket 2 from 46 minutes to 60 minutes.\n\nA device was available twice at Vancouver; initially from 9:00 AM to 9:30 AM (dwell time of 30 minutes) and then again from 12:15 PM to 1:05 PM (dwell time of 50 minutes). Both these occurrences are considered to be two independent events.\n\nIn the above scenario, the same device will be forming a part of both the Dwell Time Buckets. Bucket 1 due to event 1 from 9:00 AM to 9:30 AM and under Bucket 2 due to event 2 from 12:15 PM to 1 PM.\n\n### Bucketing\n\nDevices are bucketed based on their dwell start time in the study zone.\n\nConsidering the same scenario mentioned under Dwell Time Bucketing section above with a Time Bucket Size of 120 minutes; the output will be comprised of 4 buckets (two time buckets and two dwell time buckets; one for each time bucket) as depicted wiht the help of a table below:\n\n| Time Bucket Size | Dwell Time From | Dwell Time To |\n| --- | --- | --- |\n| 9 AM to 11 AM | 30 | 45 |\n| 9 AM to 11 AM | 46 | 60 |\n| 11 AM to 1 PM | 30 | 45 |\n| 11 AM to 1 PM | 46 | 6 |\n\nThe output will be as follows:\n\n| Time Bucket Size | Dwell Time From | Dwell Time To | Count | Reason |\n| --- | --- | --- | --- | --- |\n| 9 AM to 11 AM | 30 | 45 | 1 | Event 1 start time is 9:00 AM and hence falls under Time Bucket 9 AM to 11 AM and the device dwelled for 30 minutes and hence falls under Dwell Time Bucket 30 to 45 |\n| 9 AM to 11 AM | 46 | 60 | 0 | |\n| 11 AM to 1 PM | 30 | 45 | 0 | |\n| 11 AM to 1 PM | 46 | 6 | 1 | Event 2 start time is 12:15 PM and hence falls under Time Bucket 11 AM to 1 PM and device dwelled for 50 minutes and hence falls under Dwell Bucket 46 to 60 |\n\n### Exclusions\n\nBased on Exclustion Type selected, devices will be identified and removed from the study area selected under \"inpute geo-id\".\n\nConsider a scenario wherein Dwell Time Analysis is required to be conducted for the devices who are identified as Workers in Vancouver. In this case, excluding 'Non-Workers' will provide the required output.\n\n# API Descriptions - Home\n\n### Description\n\nThe Home end-point returns count of devices available in each input study zone broken-down by their corresponding Home Location as specified by the input parameters.\n\nStudy zone specified within the \"input geo-id\" is considered to be the visiting location whereas the study zone specified within the \"output geo-id\" is considered to be the Home location.\n\nAll the devices available in the visiting location between the specified start and end times will be qualified to be forming a part of the output.\n\n### Example\n\nHow many devices were at Burnaby (Visiting Location) on May 1, 2022 between 9 AM and 1 PM whose Home Location was Vancouver.\n\n### Dwell Time\n\nMinimum and Maximum Dwell Time is only applied to the study zone specified within the “input geo-id” i.e. the study zone considered to be the Visiting Location.\n\nConsider a resident device of Vancouver was at Burnaby for 20 minutes during the specified study period.\n\nIn this case, if the Minimum Dwell Time is set to anything in excess of 20 minutes, this device will be excluded from the output; similarly, if the Maximum Dwell Time is set to anything less than 20 minutes will also exclude this device from the output.\n\n### Exclusions\n\nBased on the Exclusion Types selected, devices will be identified and removed from the study area considered to be the Visiting Location.\n\nConsider a resident device of Vancouver who’s work location is Burnaby and was at Burnaby during the specified study period. In this case, excluding ‘Workers’ will exclude this device from the output.\n\n### Bucketing\n\nDevices are bucketed based on their availability in the study zone considered to be the Visiting Location.\n\nConsider a case wherein the Start Time and End Time are specified as 9 AM and 1 PM respectively, and the Time Bucket Size is set to 120 minutes; output will be comprised of two buckets: Bucket 1 from 9 AM to 11 AM and Bucket 2 from 11 AM to 1 PM. Resident device of Vancouver was available at Burnaby from 10 AM to 10:20 AM.\n\nIn this case, this device will be forming a part of output under Bucket 1.\n\n# API Descriptions - OD Matrix\n\n### Description\n\nOD Matrix end-point performs travel analysis (people movement analysis) between two or more study areas. It provides the number of devices that traveled along with the total no. of trips between the matrix (selected study zones/areas) as specified by the input parameters.\n\nAt least two study zones must be selected as a part of “input geo-id”.\n\n### Example\n\nNo. of devices traveled from Vancouver (Origin) to Burnaby (Destination) and vice versa i.e. no. of devices that traveled from Burnaby (Origin) to Vancouver (Destination) along with the total no. of trips on April 10 2022 between 9 AM and 1 PM.\n\n### Dwell Time\n\nMinimum and Maximum Dwell Times will be applied to both the study areas i.e. Origin as well as Destination.\n\nConsider a device traveling from Vancouver to Burnaby dwelled for 15 minutes in Vancouver and 20 minutes in Burnaby.\n\nIn this case, if Minimum Dwell Time is set to anything in excess of 20 minutes, this trip will be excluded from the output; similarly, if the Maximum Dwell Time is set to anything less than 15 minutes will also exclude this trip from the output.\n\n### Exclusions\n\nExclusion Types selected will remove devices from the study area considered to be the Origin.\n\nConsider a resident device of Vancouver who traveled from Vancouver to Burnaby and from Burnaby back to Vancouver.\n\nIn this case, excluding ‘Residents’ will exclude this device while calculating the trips from Vancouver (considered as Origin) to Burnaby (considered as Destination) but will be considered in the output while calculating the trips from Burnaby (considered as Origin) to Vancouver (considered as Destination).\n\n### Bucketing\n\nTrips are bucketed based on when the trip originated from the study area considered to be the Origin.\n\nConsider a case wherein the Start Time and End Time are specified as 9 AM and 1 PM respectively, and the Time Bucket Size is set to 120 minutes; output will be comprised of two buckets: Bucket 1 from 9 AM to 11 AM and Bucket 2 from 11 AM to 1 PM. Device traveling from Vancouver to Burnaby started from Vancouver at 10:30 AM reached Burnaby at 12:30 PM.\n\nIn this case, the trip will be forming a part of output under Bucket 1 for Origin: Vancouver and Destination: Burnaby.\n\n# API Descriptions - Origin\n\n### Description\n\nOrigin end-point returns the count of devices with trips originating from each output study zone and terminating to each input study zone as specified by the input parameters.\n\nStudy zone specified within the “input geo-id” is considered to be the Destination whereas the study zone specified within the “output geo-id” is considered to be the Origin.\n\nFor a device to be qualified in the output, the trip must start (originate) and end (terminate) between the specified start and end times.\n\n### Pass-through\n\nIn addition to the above, Origin end-point also provides an option to select pass-through study zones.\n\nWith pass-through study zone(s) selected, Origin end-point will return the count of devices with trips originating from the study zone selected under output geo-id, passing through the study zones(s) selected pass-through geo-id and terminating to study zone selected under input geo-id.\n\nIn case of multiple study zones selected under pass-through, the sequence of the trip will be determined based on the order in which the pass-through study zones have been selected.\n\nConsider a scenarion wherein two study zones 'A' and 'B' have been selected under pass-through geo-id. The output would only contain the count of devices which travelled from Origin->A->B->Destination. Devices travelling through an alterate route from Origin to Destination for e.g., Origin->A->Destination or Origin->B->Destination or Origin->B->A->Destination will not be included in the output.\n\n### Example\n\nHow many devices traveled from Vancouver (Origin) to Burnaby (Destination) on May 1, 2022 between 9 AM and 1 PM.\n\nHow many devices travelled from Vancouver (Origin) to Surrey (Destination) via Burnaby (Pass-through) on May 1, 2022 between 9 AM and 1 PM.\n\n### Dwell Time\n\nMinimum and Maximum Dwell Times can be specified independently for study zones within each group i.e. Origin, Destination and Pass-through study zones or can be specified globally which will be applied to all the study zones across all groups.\n\nConsider a device traveling from Vancouver to Burnaby dwelled for 30 minutes in Vancouver as well as Burnaby.\n\nIn this case, if the Minimum Dwell Time is set to anything in excess of 30 minutes, this device will be excluded from the output; similarly, if the Maximum Dwell Time is set to anything less than 30 minutes will also exclude this device from the output.\n\n### Exclusions\n\nExclusion Types selected will remove devices from the study area considered to be the Destination.\n\nConsider a resident device of Burnaby who traveled from Vancouver to Burnaby during the specified study period. In this case, excluding ‘Residents’ will exclude this device from the output.\n\n### Bucketing\n\nDevices are bucketed based on when the trip terminated (i.e. reached the Destination study zone).\n\nConsider a case wherein the Start time and End time are specified as 9 AM and 1 PM respectively, and the Time Bucket Size is set to 120 minutes; output will be comprised of two buckets: Bucket 1 from 9 AM to 11 AM and the Bucket 2 from 11 AM to 1 PM. Device traveling from Vancouver to Burnaby started from Vancouver at 10:30 AM reached Burnaby at 12:30 PM.\n\nIn this case, this device will be forming a part of output under Bucket 2.\n\n# API Descriptions - Repeat Visitation\n\n### Description\n\nRepeat Visitation end-point returns the number of unique devices available in the study zone more than once based on specified by the input parameters.\n\nRepeat Visitation end-point like Unique end-point analyzes each study zone independently and hence only contains “input geo-id” as an input.\n\nAll the devices available in the study zone more than once i.e. has more than one independent event and each event between the specified start and end times will be qualified to be forming a part of the output. This is further explained under Dwell Time section below.\n\n### Example\n\nHow many devices went to Vancouver on May 1, 2022 more than once between 9 AM and 1 PM.\n\n### Dwell Time\n\nMinimum and Maximum Dwell Time is applied to the study zone specified within “input geo-id”.\n\nConsider a case wherein a device was available twice at Vancouver; initially from 9:00 AM to 9:20 AM (dwell time 20 minutes) and then again from 12:15 PM to 1 PM (dwell time 45 minutes). Both these occurrences are considered to be two independent events and hence the device will be qualified to be forming a part of the output.\n\nIn the above case, if Minimum Dwell Time is set to anything in excess of 20 minutes, the device will be excluded from the output; similarly, if the Maximum Dwell Time is set to anything less than 45 minutes will also exclude this device from the output.\n\n### Bucketing\n\nDevices are bucketed based on their availability in the study zone.\n\nConsider a case wherein the Start Time and End Time are specified as 9 AM and 1 PM respectively, and the Time Bucket Size is set to 120 minutes; output will be comprised of two buckets: Bucket 1 from 9 AM to 11 AM and Bucket 2 from 11 AM to 1 PM. Device was available at Vancouver from 9:30 AM to 10 AM and then again from 12:30 PM to 1 PM.\n\nIn this case, this device will be forming a part of output under both of these buckets.\n\nConsider a different scenario wherein a device was available at Vancouver from 9:30 AM to 10 AM and then again from 10:30 AM to 10:45 AM; in this case, the device will be forming a part of the output only under Bucket 1.\n\n# API Descriptions - Total Trip\n\n### Description\n\nTotal Trip end-point returns the total number of trips made by devices to a study zone over a given period of time based on the input parameters.\n\nSimilar to Unique and Repeat Visitation end-points, Total Trip end-point analyzes each study zone independently and hence contains only “input geo-id” as an input.\n\n### Example\n\nHow many trips did devices take to Vancouver on April 1, 2022 between 9 AM and 1 PM.\n\n### Dwell Time\n\nMinimum and Maximum Dwell Time is applied to the study zone specified within “input geo-id”.\n\nConsider a device who took a trip to Vancouver was available at Vancouver for 20 minutes during the specified study period i.e. entered Vancouver at 9:00 AM and left Vancouver at 9:20 AM.\n\nIn this case, if the Minimum Dwell Time is set to anything in excess of 20 minutes, the trip made by this device will be excluded from the output; similarly, if the Maximum Dwell Time is set to anything less than 20 minutes will also exclude the trip made by this device from the output.\n\nDwell Time is calculated for each independent trip (event). Consider a case wherein a device took two trips to Vancouver during the specified study period; first trip/event from 9 AM to 9:20 AM (dwell time of 20 minutes) and the second trip/event from 12:15 PM to 1 PM (dwell time of 45 minutes).\n\nIn this case, if the Maximum Dwell Time is set to 30 minutes, only the first trip will be forming a part of the output. In the second query, if the Minimum Dwell Time is set to 30 minutes, only the second trip will be forming a part of the output.\n\nNow consider a case wherein Minimum Dwell Time is set to 15 minutes and Maximum Dwell Time is set to 60 minutes. In this case, both the trips will be included in the output.\n\n### Exclusions\n\nBased on Exclusion Type selected, devices will be identified and removed from the study area selected under “input geo-id’.\n\nConsider a resident device of Vancouver who travelled in and out of Vancouver multiple times during the specified study period. In this case, excluding ‘Residents’ will exclude all the trips made by this device from the output.\n\n### Bucketing\n\nTrips are bucketed based on when the device entered the study zone.\n\nConsider a case wherein the Start Time and End Time are specified as 9 AM and 1 PM respectively, and the Time Bucket Size is set to 120 minutes; output will be comprised of two Buckets: Bucket 1 from 9 AM to 11 AM and Bucket 2 from 11 AM to 1 PM. Device took a trip to Vancouver, entered Vancouver at 9 AM and left Vancouver at 12:30 PM.\n\nIn this case, this trip will be forming a part of the output under Bucket 1.\n\n# API Descriptions - Trade Area\n\n### Description\n\nA trade area is a geographic area from which a community/business generates the majority of its customers.\n\nTrade Area end-point returns for each study zone selected in “output geo-id”, a list of classification (Primary/Secondary/Tertiary) for the study zone selected in “input geo-id”.\n\nTrade Area defines where customers live (output geo-id) and how far they are likely to travel to a particular business district/area (input geo-id).\n\nTrade Area is built using a weighted function that takes into account the following parameters to calculate a score between 0 and 1 for each of the study zones selected under output geo-id:\n\n• Count Weight: is a 0 to 1 scale and represents how important the unique count is in classifying if the study zone is Primary, Secondary or Tertiary \n• Trip Weight: is a 0 to 1 scale and represents how important total number of trips are in classifying if the study zone is Primary, Secondary or Tertiary \n• Distance Weight: is a 0 to 1 scale and represents how important distance is in classifying if the study zone is Primary, Secondary and Tertiary\n\nPrimary and Secondary Threshold sets the bounds at which the equation will separate out the Primary, Secondary and Tertiary zones.\n\nThe classification/category for a particular study zone selected under “output geo-id” is relative to the study zone selected under “input geo-id” and based upon the other study zones selected under “output geo-id”. If only one study zone is selected under “output geo-id”, Trade Area end-point will always return the category as ‘Primary’ as the score for one study zone will always be 1.\n\nTrade Area end-point works best when the sum of Count Weight, Trip Weight and Distance Weight is 1.\n\n### Example\n\nConsider a scenario wherein 100 resident devices of Victoria and 300 resident devices of Vancouver were at business district Surrey between the study period selected. Classification of Victoria and Vancouver study zones for business district Surrey based on Count Weight 1, Primary Threshold 0.8 and Secondary Threshold 0.5 will be as follows:\n\n| Input Geo-ID | Output Geo-ID | Category |\n| --- | --- | --- |\n| Surrey | Victoria | Tertiary |\n| Surrey | Vancouver | Secondary |\n\nConsider a scenario wherein a total of 150 trips were made by resident devices of Victoria and 800 trips were made by resident devices of Vancouver to business district Surrey between the study period selected. Classification of Victoria and Vancouver study zones for business district Surrey based on Count Weight 1, Primary Threshold 0.8 and Secondary Threshold 0.3 will be as follows:\n\n| Input Geo-ID | Output Geo-ID | Category |\n| --- | --- | --- |\n| Surrey | Victoria | Tertiary |\n| Surrey | Vancouver | Primary |\n\n# API Descriptions - Unique\n\n### Description\n\nUnique end-point returns the number of unique devices available in the input study zone based on the input parameters.\n\nUnique end-point analyzes each study zone independently and hence only contains “input geo-id” as an input as compared to some of the other end-points like Home, OD matrix etc. wherein study zone specified as a part of “input geo-id” is analyzed based on it’s dependency on study zone specified as a part of “output geo-id”.\n\nAll the devices available in the input study zone between the specified start and end times will be qualified to be forming a part of the output.\n\n### Example\n\nHow many unique devices visited Vancouver on May 1, 2022 between 9 AM and 1 PM.\n\n### Dwell Time\n\nMinimum and Maximum Dwell Times are applied to the study zone specified within “input geo-id”.\n\nConsider a device was available at Vancouver for 20 minutes during the specified study period.\n\nIn this case, if the Minimum Dwell Time is set to anything in excess of 20 minutes, this device will be excluded from the output; similarly, if the Maximum Dwell Time is set to anything less than 20 minutes will also exclude this device from the output.\n\nDwell Time is calculated for each independent event and not cumulated for a device based on study period. Consider a case wherein a device was available twice at Vancouver; initially from 9:00 AM to 9:20 AM (dwell time 20 minutes) and then again from 12:15 PM to 1 PM (dwell time 45 minutes). Both these occurrences are considered to be two independent events.\n\nIn this case, if the Maximum Dwell Time is set to 30 minutes, this device will be forming a part of the output due to the first event from 9 AM to 9:20 AM. In the second query, if the Minimum Dwell Time is set to 30 minutes, the same device will again be forming a part of the output, this time due to the second event from 12:15 PM to 1 PM.\n\nFor further clarification, Unique end-point returns number of unique devices and not the number of unique events and hence, even if a device has two independent events and they both qualify to be forming a part of the output based on specified input parameters, the device will only be counted once in the output.\n\nConsider a case wherein the Minimum Dwell Time is set to 15 minutes and Maximum Dwell \nTime is set to 60 minutes. In this case, both the events mentioned above are eligible to be forming a part of the output, but this device will only be considered once in the output.\n\n### Bucketing\n\nDevices are bucketed based on their availability in the study zone.\n\nConsider a case wherein the Start Time and End Time are specified as 9 AM and 1 PM respectively, and the Time Bucket Size is set to 120 minutes; output will be comprised of two buckets: Bucket 1 from 9 AM to 11 AM and Bucket 2 from 11 AM to 1 PM. Device was available at Vancouver from 9:30 AM to 12:30 PM. \nIn this case, this device will be forming a part of output under both of these buckets.\n\nConsider a different scenario wherein a device was available at Vancouver only from 9:30 AM to 10 AM; in this case, the device will be forming a part of the output only under Bucket 1.\n\n# API Descriptions - Work\n\n### Description\n\nThe Work end-point returns count of devices available in each input study zone broken-down by their corresponding Work Location as specified by the input parameters.\n\nStudy zone specified within the \"input geo-id\" is considered to be the Visiting Location whereas the study zone specified within the \"output geo-id\" is considered to be the Work Location.\n\nAll the devices available in the visiting location between the specified start and end times will be qualified to be forming a part of the output.\n\n### Example\n\nHow many devices were at Burnaby (Visiting Location) on May 1, 2022 between 9 AM and 1 PM whose Work Location was Vancouver.\n\n### Dwell Time\n\nMinimum and Maximum Dwell Time is only applied to the study zone specified within the “input geo-id” i.e. study zone considered to be the Visiting Location.\n\nConsider a resident device of Vancouver was at Burnaby for 20 minutes during the specified study period.\n\nIn this case, if the Minimum Dwell Time is set to anything in excess of 20 minutes, this device will be excluded from the output; similarly, if the Maximum Dwell Time is set to anything less than 20 minutes will also exclude this device from the output.\n\n### Exclusions\n\nBased on the Exclusion Types selected, devices will be identified and removed from the study area considered to be the Visiting Location.\n\nConsider a device who’s work location is Vancouver and is a resident device of Burnaby and was at Burnaby during the specified study period. In this case, excluding ‘Residents’ will exclude this device from the output.\n\n### Bucketing\n\nDevices are bucketed based on their availability in the study zone considered to be the Visiting Location.\n\nConsider a case wherein the Start Time and End Time are specified as 9 AM and 1 PM respectively, and the Time Bucket Size is set to 120 minutes; output will be comprised of two buckets: Bucket 1 from 9 AM to 11 AM and Bucket 2 from 11 AM to 1 PM. Device, who’s work location is Vancouver was available at Burnaby from 10 AM to 10:20 AM.\n\nIn this case, this device will be forming a part of output under Bucket 1.\n\n# Count - APIs Reference Section\n\n## Telus Insights Location API\n\n- **Version:** 1.0\n- **Host:** location-api.insights.telus.com/product/insightsRequest/v1\n- **Protocols:** `https`\n \n\n##### More Info\n\n- **Contact Us by Email** **\\-** [TelusInsightsAppSupport@telus.com](mailto:TelusInsightsAppSupport@telus.com)\n \n\nWe have developed the following API services to help customers utilize TELUS Geo-intelligence data assets and help answer a range of questions around location and movement patterns within Canada.","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"19774759","collectionId":"d8e042de-3754-42b6-beb6-a174697eddf8","publishedId":"2s93z9cNmr","public":true,"publicUrl":"https://docs.insights.telus.com","privateUrl":"https://go.postman.co/documentation/19774759-d8e042de-3754-42b6-beb6-a174697eddf8","customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"4B286D"},"documentationLayout":"classic-single-column","customisation":{"metaTags":[{"name":"description","value":""},{"name":"title","value":""}],"appearance":{"default":"light","themes":[{"name":"dark","logo":null,"colors":{"top-bar":"212121","right-sidebar":"303030","highlight":"FF6C37"}},{"name":"light","logo":null,"colors":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"4B286D"}}]}},"version":"8.10.1","publishDate":"2023-06-28T21:19:35.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{"title":"","description":""},"logos":{"logoLight":null,"logoDark":null}},"statusCode":200},"environments":[{"name":"Telus Insights API - Client Credentials","id":"e59821b2-22e0-4911-b22e-f3ee67fd0bd4","owner":"23335868","values":[{"key":"AccessTokenURL","value":"https://apigw-pr.telus.com/token","enabled":true},{"key":"AuthCodeClientId","value":"","type":"secret","enabled":true},{"key":"AuthCodeClientSecret","value":"","type":"secret","enabled":true},{"key":"AuthCodeScopeIds","value":"814","enabled":true}],"published":true}],"user":{"authenticated":false,"permissions":{"publish":false}},"run":{"button":{"js":"https://run.pstmn.io/button.js","css":"https://run.pstmn.io/button.css"}},"web":"https://www.getpostman.com/","team":{"logo":"https://res.cloudinary.com/postman/image/upload/t_team_logo_pubdoc/v1/team/768118b36f06c94b0306958b980558e6915839447e859fe16906e29d683976f0","favicon":"https://telus.com/favicon.ico"},"isEnvFetchError":false,"languages":"[{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"HttpClient\"},{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"RestSharp\"},{\"key\":\"curl\",\"label\":\"cURL\",\"variant\":\"cURL\"},{\"key\":\"dart\",\"label\":\"Dart\",\"variant\":\"http\"},{\"key\":\"go\",\"label\":\"Go\",\"variant\":\"Native\"},{\"key\":\"http\",\"label\":\"HTTP\",\"variant\":\"HTTP\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"OkHttp\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"Unirest\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"Fetch\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"jQuery\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"XHR\"},{\"key\":\"c\",\"label\":\"C\",\"variant\":\"libcurl\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Axios\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Native\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Request\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Unirest\"},{\"key\":\"objective-c\",\"label\":\"Objective-C\",\"variant\":\"NSURLSession\"},{\"key\":\"ocaml\",\"label\":\"OCaml\",\"variant\":\"Cohttp\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"cURL\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"Guzzle\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"HTTP_Request2\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"pecl_http\"},{\"key\":\"powershell\",\"label\":\"PowerShell\",\"variant\":\"RestMethod\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"http.client\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"Requests\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"httr\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"RCurl\"},{\"key\":\"ruby\",\"label\":\"Ruby\",\"variant\":\"Net::HTTP\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"Httpie\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"wget\"},{\"key\":\"swift\",\"label\":\"Swift\",\"variant\":\"URLSession\"}]","languageSettings":[{"key":"csharp","label":"C#","variant":"HttpClient"},{"key":"csharp","label":"C#","variant":"RestSharp"},{"key":"curl","label":"cURL","variant":"cURL"},{"key":"dart","label":"Dart","variant":"http"},{"key":"go","label":"Go","variant":"Native"},{"key":"http","label":"HTTP","variant":"HTTP"},{"key":"java","label":"Java","variant":"OkHttp"},{"key":"java","label":"Java","variant":"Unirest"},{"key":"javascript","label":"JavaScript","variant":"Fetch"},{"key":"javascript","label":"JavaScript","variant":"jQuery"},{"key":"javascript","label":"JavaScript","variant":"XHR"},{"key":"c","label":"C","variant":"libcurl"},{"key":"nodejs","label":"NodeJs","variant":"Axios"},{"key":"nodejs","label":"NodeJs","variant":"Native"},{"key":"nodejs","label":"NodeJs","variant":"Request"},{"key":"nodejs","label":"NodeJs","variant":"Unirest"},{"key":"objective-c","label":"Objective-C","variant":"NSURLSession"},{"key":"ocaml","label":"OCaml","variant":"Cohttp"},{"key":"php","label":"PHP","variant":"cURL"},{"key":"php","label":"PHP","variant":"Guzzle"},{"key":"php","label":"PHP","variant":"HTTP_Request2"},{"key":"php","label":"PHP","variant":"pecl_http"},{"key":"powershell","label":"PowerShell","variant":"RestMethod"},{"key":"python","label":"Python","variant":"http.client"},{"key":"python","label":"Python","variant":"Requests"},{"key":"r","label":"R","variant":"httr"},{"key":"r","label":"R","variant":"RCurl"},{"key":"ruby","label":"Ruby","variant":"Net::HTTP"},{"key":"shell","label":"Shell","variant":"Httpie"},{"key":"shell","label":"Shell","variant":"wget"},{"key":"swift","label":"Swift","variant":"URLSession"}],"languageOptions":[{"label":"C# - HttpClient","value":"csharp - HttpClient - C#"},{"label":"C# - RestSharp","value":"csharp - RestSharp - C#"},{"label":"cURL - cURL","value":"curl - cURL - cURL"},{"label":"Dart - http","value":"dart - http - Dart"},{"label":"Go - Native","value":"go - Native - Go"},{"label":"HTTP - HTTP","value":"http - HTTP - HTTP"},{"label":"Java - OkHttp","value":"java - OkHttp - Java"},{"label":"Java - Unirest","value":"java - Unirest - Java"},{"label":"JavaScript - Fetch","value":"javascript - Fetch - JavaScript"},{"label":"JavaScript - jQuery","value":"javascript - jQuery - JavaScript"},{"label":"JavaScript - XHR","value":"javascript - XHR - JavaScript"},{"label":"C - libcurl","value":"c - libcurl - C"},{"label":"NodeJs - Axios","value":"nodejs - Axios - NodeJs"},{"label":"NodeJs - Native","value":"nodejs - Native - NodeJs"},{"label":"NodeJs - Request","value":"nodejs - Request - NodeJs"},{"label":"NodeJs - Unirest","value":"nodejs - Unirest - NodeJs"},{"label":"Objective-C - NSURLSession","value":"objective-c - NSURLSession - Objective-C"},{"label":"OCaml - Cohttp","value":"ocaml - Cohttp - OCaml"},{"label":"PHP - cURL","value":"php - cURL - PHP"},{"label":"PHP - Guzzle","value":"php - Guzzle - PHP"},{"label":"PHP - HTTP_Request2","value":"php - HTTP_Request2 - PHP"},{"label":"PHP - pecl_http","value":"php - pecl_http - PHP"},{"label":"PowerShell - RestMethod","value":"powershell - RestMethod - PowerShell"},{"label":"Python - http.client","value":"python - http.client - Python"},{"label":"Python - Requests","value":"python - Requests - Python"},{"label":"R - httr","value":"r - httr - R"},{"label":"R - RCurl","value":"r - RCurl - R"},{"label":"Ruby - Net::HTTP","value":"ruby - Net::HTTP - Ruby"},{"label":"Shell - Httpie","value":"shell - Httpie - Shell"},{"label":"Shell - wget","value":"shell - wget - Shell"},{"label":"Swift - URLSession","value":"swift - URLSession - Swift"}],"layoutOptions":[{"value":"classic-single-column","label":"Single Column"},{"value":"classic-double-column","label":"Double Column"}],"versionOptions":[],"environmentOptions":[{"value":"0","label":"No Environment"},{"label":"Telus Insights API - Client Credentials","value":"23335868-e59821b2-22e0-4911-b22e-f3ee67fd0bd4"}],"canonicalUrl":"https://docs.insights.telus.com/view/metadata/2s93z9cNmr"}