Before you Begin

Get started with using the Altitude API by understanding the requirements for every API call, the different ways to make an API call, and the API workflow.

Getting Altitude Credentials

In order to use the Altitude API, you need to have the required credentials, which would be provided to you by the Altitude team.

Once you are registered as an Altitude Customer, you will receive an email with key information that you should take note of.

Business Rules

Note:

Altitude tables store sub-state or provincial geographies as counties. This is a standard definition for the United States. However, for Canada, the designation of county covers census subdivisions or various boundaries, such as counties, cities, or townships.

When you sign up for Altitude, a new database is created for you to access the Altitude applications. An API request is made to store your database name, license type, expiry date, an array of application IDs, data start date, data end date, and an array of county IDs in a BigQuery table. Depending on your license type, you may only have access to data captured between the data start and data end dates. You may only have access to data on or before the expiry date. Lastly, all users only have access to data for the counties specified in the county ID array, as well as the applications specified in the application ID array. This is all done on a per-database basis, so one database may have access to different counties and applications from another one.

API Workflow

This is the process the Altitude API follows for every request before it fetches the requested data, ensuring the user is authenticated and that the requested data is covered by their database license, before retrieving it back to the user.
  1. Authentication check: Database, userName, and sessionId are sent with every API request. If the user's credentials are not validated, the API request fails with an Incorrect login credentials error.
  2. Authorization and license check: once authenticated, a BigQuery check validates the database's permissions for geography, application/module, and date range against the requested data.
  3. Data retrieval: If all of these checks pass, a BigQuery query is run based on the queryType that was passed to the API request.
This layered validation approach ensures robust security and adherence to licensing agreements. By performing the three critical license and authorization checks simultaneously in a single BigQuery query (Step 2), the API minimizes latency and avoids unnecessary resource consumption before retrieving the main data, thereby promoting efficiency and data integrity.

The request can fail from any of the following reasons:

Incorrect login credentials
Invalid username and or password.
Geography
The database must be licensed to access the geographic area requested.
Application/Module
The database must be licensed to use the specific application data (e.g., roads, intersections, origin/destination data) being requested.
Date Range & Expiry
The requested data date range must fall between the database's licensed start and end dates, and the current date must not be past the overall data expiry date.