TELUS

TELUS Insights Location API

The TELUS Insights Location API exposes de-identified, aggregated geo-intelligence derived from the TELUS mobile network across Canada. Consumers submit asynchronous count jobs — demographic, origin, destination, origin-destination matrix, dwell time, trade area, repeat visitation, total trip, unique devices, home and work — against uploaded shapefile study zones or built-in geofences, then poll a job identifier for results. Documentation is published publicly through Postman; the gateway at location-api.insights.telus.com is live and returns 401 without a bearer token. Access uses OAuth2 client credentials issued through the TELUS Insights Portal after a sales-led onboarding, so the API is documented publicly but is not self-serve.

GitHub

Documentation

📖
Documentation
https://docs.insights.telus.com/
📖
APIReference
https://docs.insights.telus.com/
📖
Authentication
https://raw.githubusercontent.com/api-evangelist/telus/refs/heads/main/authentication/telus-authentication.yml
📖
RateLimits
https://raw.githubusercontent.com/api-evangelist/telus/refs/heads/main/rate-limits/telus-rate-limits.yml

Other Resources

🔗
PostmanCollection
https://raw.githubusercontent.com/api-evangelist/telus/refs/heads/main/collections/telus-insights-location-api.postman_collection.json
🔗
Postman
https://docs.insights.telus.com/
🔗
Portal
https://insights.telus.com/
🔗
OAuthScopes
https://raw.githubusercontent.com/api-evangelist/telus/refs/heads/main/scopes/telus-scopes.yml
🔗
ErrorCatalog
https://raw.githubusercontent.com/api-evangelist/telus/refs/heads/main/errors/telus-problem-types.yml
🔗
Sandbox
https://raw.githubusercontent.com/api-evangelist/telus/refs/heads/main/sandbox/telus-sandbox.yml
🔗
APIsJSON
https://raw.githubusercontent.com/api-evangelist/telus/refs/heads/main/apis.yml

Postman Collection

telus-insights-location-api.postman_collection.json Raw ↑ 
{"info":{"_postman_id":"d8e042de-3754-42b6-beb6-a174697eddf8","name":"Telus Insights Location API","description":"<html><head></head><body><p><a href=\"https://www.youtube.com/watch?v=Mv29cjU5u_I\">Telus Insights</a> solution helps customers utilize TELUS Geo-intelligence data assets and help answer a range of questions around location and movement patterns within Canada.</p>\n<p>Key Highlights of TELUS Insights Location API:</p>\n<ul>\n<li>Process and record over 3B location data records per day.</li>\n<li>Data assets are enhanced using algorithmic logic, and data models providing meaningful location based insights</li>\n<li>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.</li>\n<li>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.</li>\n<li>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.</li>\n</ul>\n<h1 id=\"introduction-generalities\">Introduction - Generalities</h1>\n<h3 id=\"data-recency\">Data Recency</h3>\n<ul>\n<li>Data is collected and processed every 5 mins from our network, and through a series of data processing jobs</li>\n<li>Live data is processed, transformed, and made available within our Data Warehouse within 1-2 hours</li>\n<li>Results are provided at a minimum of 15 minute intervals to ensure privacy.</li>\n</ul>\n<h3 id=\"data-retention\">Data Retention</h3>\n<ul>\n<li>Data available from January 1, 2019</li>\n<li>Data will remain in the system for up to 5 years, starting from this date.</li>\n</ul>\n<h3 id=\"coverage--users\">Coverage / Users</h3>\n<ul>\n<li>9.8M Canadians, and 3M+ International devices (monthly average)</li>\n<li>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.</li>\n</ul>\n<h3 id=\"data-storage\">Data Storage</h3>\n<ul>\n<li>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.</li>\n</ul>\n<h3 id=\"data-privacy\">Data Privacy</h3>\n<ul>\n<li>Removal of key identifiers from the dataset, replacing them with pseudonymous persistent identifiers. More on Data Privacy <a href=\"https://www.youtube.com/watch?v=04jNbstgKlI&amp;t\">here</a>.</li>\n<li>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.</li>\n<li>All data is rounded-up to the nearest 10 counts.</li>\n<li>All results are extrapolated to represent the entire population to provide a layer of privacy.</li>\n<li>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.</li>\n<li>TELUS has updated its privacy policy to ensure that there is enough information available to the general population on what we are doing.</li>\n<li>We have sought outside expertise from a range of trusted Privacy advisors and Privacy tech companies to validate our approach</li>\n<li>Achieved Privacy By Design certification</li>\n<li>Close collaboration and partnership with TELUS Data &amp; Trust Office, ensuring inclusion in any key product decisions.</li>\n</ul>\n<h3 id=\"limitations\">Limitations</h3>\n<ul>\n<li>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.</li>\n<li>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:<ul>\n<li>June 14, 2021</li>\n<li>June 15, 2021</li>\n<li>June 16, 2021</li>\n</ul>\n</li>\n</ul>\n<h1 id=\"introduction-spatial-aggregation\">Introduction - Spatial aggregation</h1>\n<ul>\n<li>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.</li>\n<li>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.</li>\n<li>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.</li>\n<li>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.</li>\n<li>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.</li>\n</ul>\n<h1 id=\"introduction-methodologies\">Introduction - Methodologies</h1>\n<h2 id=\"assumed-primary-and-secondary-neighbourhoods-methodology\">Assumed Primary and Secondary neighbourhoods methodology</h2>\n<p>TELUS 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.</p>\n<p>The algorithm has been built in a way that the secondary neighbourhood is not confused with primary neighbourhood.​</p>\n<h2 id=\"extrapolation-methodology\">Extrapolation methodology</h2>\n<p>To 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.</p>\n<h1 id=\"introduction-insights-developer-portal\">Introduction - Insights Developer Portal</h1>\n<p><a href=\"https://insights.telus.com/\">Insights Developer Portal</a> enables the users to explore, interact and query the API through an intuitive interface.</p>\n<p>Devoloper Portal provides self-serve capabilities on top of the API such as:</p>\n<ul>\n<li>API Documentation</li>\n<li>API credentials</li>\n<li>Support desk</li>\n<li>Product notifications</li>\n<li>More to come</li>\n</ul>\n<h3 id=\"insights-developer-portal-homepage\">Insights Developer Portal Homepage</h3>\n<img src=\"https://content.pstmn.io/fa7fe848-32f4-44ee-b762-d1831d726d61/SW5zaWdodHMgRGV2ZWxvcGVyIFBvcnRhbCBIb21lcGFnZS5wbmc=\">\n\n<h1 id=\"introduction-api-integrations\">Introduction - API Integrations</h1>\n<p>​<br>In order to build automated solutions for API consumption, we recommend the following process and best practices</p>\n<h2 id=\"1-oauth-credentials\">1. OAuth Credentials</h2>\n<p>Request OAuth credentials by creating a ticket in the Portal. Check your My Account page in the portal to determine if you already have them.</p>\n<h2 id=\"2-creating-script-snippets\">2. Creating Script Snippets</h2>\n<p>To create scripts for your favorite language you can get some code snippets from the “Example Request” section for each API on this site.</p>\n<img src=\"https://content.pstmn.io/332217a9-3fd7-4025-b581-e71c2ca8ec64/U2VuZF9leGFtcGxlX3JlcXVlc3RfMi5wbmc=\" width=\"619\" height=\"308\">\n\n<img src=\"https://content.pstmn.io/26d57534-2f71-4fac-b271-c5a1dd8c9494/Sm9iIFRvb2wgU2NyZWVuc2hvdC5qcGc=\">\n\n<pre class=\"click-to-expand-wrapper is-snippet-wrapper\"><code class=\"language-bash\"># 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\" &gt;&gt; ${api_path}.${jobId}.json\n    fi\ndone\n\n</code></pre>\n<h1 id=\"introduction-api-restrictions-and-usage\">Introduction - API Restrictions and Usage</h1>\n<h2 id=\"api-restrictions\">API Restrictions</h2>\n<p>Currently 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:</p>\n<h3 id=\"1-day-queries\">1 Day Queries</h3>\n<p>Minimum Time Bucket Size of 15 min is allowed for queries ranging up to 1 day period</p>\n<h3 id=\"30-day-queries\">30 Day Queries</h3>\n<p>Minimum Time Bucket Size of 60 min is allowed only for queries ranging up to 30 days period</p>\n<h3 id=\"more-than-30-day-queries\">More than 30 Day Queries</h3>\n<p>Minimum Time Bucket Size of 24 Hrs is allowed for queries more than 30 days</p>\n<h3 id=\"concurrent-queries\">Concurrent Queries</h3>\n<p>Only run 5 concurrent queries at a time. This includes queries submitted via the API and the portal.</p>\n<h3 id=\"query-volume\">Query Volume</h3>\n<p>Only run 10 queries per hour and 100 queries per day</p>\n<h2 id=\"usage-statistics\">Usage Statistics</h2>\n<p>We 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:</p>\n<ul>\n<li>Number of monthly API Calls</li>\n<li>Number of Study Zones queried</li>\n</ul>\n<p>This will enable you to understand and administer your organization's usage against the plan's limit.</p>\n<p>'Usage Statistics' option has been made available under 'Account Settings' as depicted below:</p>\n<img src=\"https://content.pstmn.io/ddccfedf-f4c5-434f-9c5e-cb671eca69b3/VXNhZ2UgU3RhdGlzdGljcy5wbmc=\">\n\n<p>By default, the statistics will be displayed for the current month and year which could be changed using the dropdowns.</p>\n<p>There are three parts to Usage Statistics.</p>\n<p><strong>Part 1:</strong> Primary information i.e. number of monthly API Calls and number of Study Zones queried for the selected month and year as depicted below:</p>\n<img src=\"https://content.pstmn.io/255c0dc0-d673-420a-954c-4f4b8643436e/Q2FyZCAxLnBuZw==\">\n\n<p><strong>Part 2:</strong> End-point wise breakdown of the total API Calls based on the selected month and year as depicted below:</p>\n<img src=\"https://content.pstmn.io/cedb941c-e0c5-4f13-9d87-3aa456b0a08b/Q2FyZCAyLnBuZw==\">\n\n<p><strong>Part 3:</strong> 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:</p>\n<img src=\"https://content.pstmn.io/ccce0e69-0fe7-4025-87b1-e4e4ed855bf8/Q2FyZCAzLnBuZw==\">\n\n<h2 id=\"best-practices\">Best Practices</h2>\n<h3 id=\"query-processing-time\">Query Processing Time</h3>\n<p>The 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.</p>\n<h3 id=\"oauth-token\">OAuth Token</h3>\n<p>When 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.</p>\n<h3 id=\"wait-time-before-results\">Wait Time before results</h3>\n<p>The 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.</p>\n<h3 id=\"volume-of-queries\">Volume of Queries</h3>\n<p>To 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.</p>\n<h1 id=\"getting-started\">Getting Started</h1>\n<p>We 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:</p>\n<ol>\n<li>Authentication</li>\n<li>Upload Shapefile</li>\n<li>Run a job</li>\n<li>Data Dictionary and Formats</li>\n<li>Exclusion Types</li>\n<li>API Function Descriptions</li>\n</ol>\n<h1 id=\"getting-started-authentication\">Getting Started - Authentication</h1>\n<h2 id=\"telus-insights-portal\">Telus Insights Portal</h2>\n<p>Authentication to Telus Insights Portal (<a href=\"https://insights.telus.com\">https://insights.telus.com</a>) 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 <a href=\"mailto:dlTelusInsights@telus.com\">dlTelusInsights@telus.com</a>) 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 (<a href=\"mailto:do.not.reply@telus.com\">do.not.reply@telus.com</a>) that would allow you to create a password. The user ID is the email address.</p>\n<p>Note: If you are already registered with Telus Client Identity, you could start accessing Telus Insights Portal once you receive the informative email from <a href=\"mailto:dlTelusInsights@telus.com\">dlTelusInsights@telus.com</a>.</p>\n<h2 id=\"api\">API</h2>\n<p>To authenticate to the API - <a href=\"https://location-api.insights.telus.com\">https://location-api.insights.telus.com</a>, 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 <a href=\"https://docs.insights.telus.com/#introduction-api-integrations\">API Integrations page</a>.</p>\n<h1 id=\"getting-started-shapefiles-and-study-zones\">Getting Started - Shapefiles and Study Zones</h1>\n<p>A 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.</p>\n<p>Before 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.</p>\n<p>Each study area will be defined, uploaded and maintained in the system as a set of Latitude Longitude that encapsulate a geo fence.</p>\n<p>Before 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.</p>\n<p>You could either create your own <strong>Custom Shapefile</strong> using our shapefile endpoint or use one of the <strong>Public Shapefiles</strong> downloaded from <a href=\"https://www.statcan.gc.ca/en/geography?MM=1\">Stats Canada website</a> made available to you for your analysis.</p>\n<h2 id=\"public-shapefiles\">Public Shapefiles</h2>\n<p><strong>Public shapefiles</strong> are geo-spatial files that store standard areas defined by public Canadian authorities such as Census Subdivision (CSD) and Forward Sortation Areas (FSA).</p>\n<p><strong>Source of the files:</strong> <a href=\"https://www.statcan.gc.ca/en/geography?MM=1\">Stats Canada website</a></p>\n<p><strong>Type of files:</strong> Digital Boundary Files</p>\n<p><strong>Naming convention for shapefiles and study zones:</strong><br>Original 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 &lt;= 75 characters and study zone name length will be &lt;= 50 characters.<br>Following is the file and shapefile naming conventions:</p>\n<p><strong>CSD files:</strong></p>\n<pre class=\"click-to-expand-wrapper is-snippet-wrapper\"><code>public_canada_csd_CensusYear_PRCode_PRUID.zip\n\n</code></pre><p>Census 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.</p>\n<pre class=\"click-to-expand-wrapper is-snippet-wrapper\"><code>Example shapefile name: public_canada_csd_2021_bc_59.zip\nExample RequestID: public-canada-csd-2021-bc-59-zip-{random GUID}\n\n</code></pre><p>For 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.</p>\n<pre class=\"click-to-expand-wrapper is-snippet-wrapper\"><code>Example without DGUID: Victoria(CY)\nExample with DGUID: Okanagan (Part) 1(IRI)(5937801)\n\n</code></pre><p>References: <a href=\"https://www12.statcan.gc.ca/census-recensement/2021/ref/dict/az/index-eng.cfm\">Dictionary, Census of Population, 2021</a></p>\n<p><strong>FSA files:</strong></p>\n<pre class=\"click-to-expand-wrapper is-snippet-wrapper\"><code>public_canada_fsa_CensusYear_PRCode_PRUID.zip\n\n</code></pre><p>Census 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.</p>\n<pre class=\"click-to-expand-wrapper is-snippet-wrapper\"><code>Example shapefile name: public_canada_fsa_2021_bc_59.zip\nExample RequestID: public-canada-fsa-2021-bc-59-zip-{random GUID}\n\n</code></pre><p>For study zones, CFSAUID which uniquely identifies a forward sortation area composed of three alphanumeric characters.</p>\n<pre class=\"click-to-expand-wrapper is-snippet-wrapper\"><code>Example: V3T\n\n</code></pre><p>References: <a href=\"https://www150.statcan.gc.ca/n1/pub/92-179-g/2011001/tech-eng.htm\">Forward Sortation Area, Boundary File, Reference Guide</a></p>\n<p><strong>Release dates:</strong></p>\n<p>CSD Files: 2021</p>\n<p>FSA Files: 2021</p>\n<p><strong>How to use Public Shapefiles:</strong><br>Public Shapefiles are made available on the Job Tool screen below the Custom Shapefiles under Shapefile/RequestID drop-down list as depicted below.</p>\n<img src=\"https://content.pstmn.io/ee620fae-7e97-4e72-8e62-1ce930d9c05e/am9idG9vbF80LnBuZw==\">\n\n<p>Geofence endpoint will also return the list of Public Shapfile Request IDs below the Custom Shapefile Request IDs list.</p>\n<p><strong>Future Changes:</strong> A separate section under 'Study Zone Management' in the Portal to view details of Public Shapefiles.</p>\n<h2 id=\"uploading-a-shapefile--preparing-your-study-zones\">Uploading a shapefile / preparing your Study Zones</h2>\n<p>This section explains the process of uploading custom shapefiles.</p>\n<p>The system supports multiple formats including Google’s KML (Keyhole Markup Language), ESRI Shapefiles and GeoJson.</p>\n<p>Our shapefile endpoint allows you to do the following:</p>\n<ul>\n<li>Upload your own unique shapefiles and polygons (study zones/areas)</li>\n<li>Polygons could be anything including but not limited to:<ul>\n<li>Province</li>\n<li>City</li>\n<li>Region</li>\n<li>Postal codes</li>\n</ul>\n</li>\n<li>Shapefile information including study zone names are stored for future use</li>\n<li>This information is stored in our application database for fast processing</li>\n</ul>\n<p>Once the shapefile has been accepted by the system, it will return a <code>requestID</code>. This <code>requestID</code>, once processed, along with the Study Zone names will be what you use to make the calls to the Count endpoints.</p>\n<h3 id=\"shapefile-format-requirements\">Shapefile format requirements</h3>\n<div class=\"click-to-expand-wrapper is-table-wrapper\"><table>\n<thead>\n<tr>\n<th>Requirements</th>\n<th>Details</th>\n</tr>\n</thead>\n<tbody>\n<tr>\n<td>Format</td>\n<td>.kml (Google Keyhole Markup)  <br>.zip (ESRI Shapefile)  <br>.json</td>\n</tr>\n<tr>\n<td>Formats in ZIP file</td>\n<td>.dbf, .prj, .shp, .shx, .cpg</td>\n</tr>\n<tr>\n<td>Max File Size</td>\n<td>25 MB</td>\n</tr>\n<tr>\n<td>Max Row Size for Study Zone</td>\n<td>4 MB</td>\n</tr>\n<tr>\n<td>Column Names</td>\n<td>Add 'study_zone' column and list out all relevant polygon coordinates</td>\n</tr>\n<tr>\n<td>Max no. of Study Zones</td>\n<td>2000</td>\n</tr>\n<tr>\n<td>File name length</td>\n<td>75 characters</td>\n</tr>\n<tr>\n<td>Study Zone name length</td>\n<td>50 characters</td>\n</tr>\n<tr>\n<td>Study Zone name</td>\n<td>1. Must be unique  <br>2. Must NOT contain backslashes or quotation marks  <br>3. Cannot be changed after upload</td>\n</tr>\n<tr>\n<td>Polygon Coordinates</td>\n<td>Our system only handles flat geometries i.e. the coordinates must be two dimensional  <br>Sample coordinates: -100.0000000, 50.0000000  <br>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.  <br>Sample coordinates with third dimension: -100.0000000, 50.0000000, 2  <br>Coordinates stored for processing: -100.0000000, 50.0000000</td>\n</tr>\n</tbody>\n</table>\n</div><img src=\"https://content.pstmn.io/1719071e-cd75-4723-b835-da0fbce7d9ae/U2hhcGVmaWxlXzUucG5n\">\n\n<img src=\"https://content.pstmn.io/c82978d4-c1bb-4898-a73c-87ebb28a6abf/dXBsb2FkX3NoYXBlZmlsZV82LnBuZw==\">\n\n<h1 id=\"getting-started-run-a-job\">Getting Started - Run a job</h1>\n<p>We can run a job through below two options:</p>\n<ul>\n<li><strong>Insights Developer Portal</strong></li>\n<li><strong>Rest API</strong></li>\n</ul>\n<h2 id=\"insights-developer-portal\">Insights Developer Portal</h2>\n<p>Insights 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.</p>\n<img src=\"https://content.pstmn.io/4fa8bd64-89ad-4b59-abca-c1200b180084/SW5zaWdodHMgRGV2ZWxvcGVyIFBvcnRhbC5wbmc=\">\n\n<p>You can also edit an existing job and re-run it from View Data Jobs screen.</p>\n<h2 id=\"rest-api\">Rest API</h2>\n<h3 id=\"asynchronous-computation\">Asynchronous Computation</h3>\n<ul>\n<li>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.</li>\n<li>API responds synchronously as quickly as possible. It returns an HTTP 202 (Accepted) status code, acknowledging that the request has been received for processing.</li>\n<li>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).</li>\n<li>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.</li>\n</ul>\n<img src=\"https://content.pstmn.io/c1ce7978-1367-48c4-926b-8979efbf0f25/cmVxdWVzdF9mbG93XzgucG5n\">\n\n<h2 id=\"job-queues\">Job Queues</h2>\n<p>We 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.</p>\n<p>Queries are processed based on available computation space.</p>\n<p>Most of the time, your results will be available on your first <code>GET</code> 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 <code>GET</code> every 5 minutes.</p>\n<p>The 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.</p>\n<h2 id=\"https-post-request\">HTTPS POST request</h2>\n<p>The 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.</p>\n<pre class=\"click-to-expand-wrapper is-snippet-wrapper\"><code class=\"language-json\">{\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</code></pre>\n<p>There are multiple ways to POST a request to a REST API.</p>\n<p><strong>Best Practices:</strong></p>\n<ul>\n<li>Use an extension for your browser such as:<ul>\n<li>Chrome: Postman, Advanced REST Client</li>\n<li>Firefox: REST Easy, RESTClient</li>\n</ul>\n</li>\n<li>As a POST method, parameters of the request are not directly included in the URL. You need to attach them to your request.</li>\n<li>The parameters/arguments are always in JSON format, with the returned response always in JSON.</li>\n<li>The specific parameters depend on the API function you want to call.<ul>\n<li>The JSON response can be converted easily to CSV / excel using a variety of tools from the internet.</li>\n</ul>\n</li>\n</ul>\n<p>To find more information on what arguments to pass, please refer to the <a href=\"https://docs.insights.telus.com/#count-apis-reference-section\">API's Reference section</a></p>\n<h2 id=\"https-get-request\">HTTPS GET request</h2>\n<p>To 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.</p>\n<ul>\n<li>After GET request is submitted, if the computation is completed, this method will return the results similar to below results.</li>\n</ul>\n<pre class=\"click-to-expand-wrapper is-snippet-wrapper\"><code class=\"language-json\">{\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</code></pre>\n<ul>\n<li>Otherwise it will return a status of PROCESSING until request is completed.</li>\n</ul>\n<pre class=\"click-to-expand-wrapper is-snippet-wrapper\"><code class=\"language-json\">{\n  \"jobId\": \"84f4a1ba-a0d7-41d8-bc09-944440da6476\",\n  \"status\": \"Processing\",\n  \"link\": {\n    \"rel\": \"dwelltime\",\n    \"url\": \"/

# --- truncated at 32 KB (263 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/telus/refs/heads/main/collections/telus-insights-location-api.postman_collection.json