Handling Special Cases

You will need to handle query types marked with an asterisk (*) differently to avoid API timeouts or errors due to large amounts of data or long processing time.

To avoid these issues, make an API request to create a BigQuery job to run the query, then make API requests to poll the job and see if it is finished. Once the job is finished, you need to return the data in increments of a certain number of records at a time defined by the resultsLimit parameter, as the API cannot return data greater than 10MB.

Step 1: createQueryJob

This API can be used to create a job for any of the APIs above that have an asterisk. The request parameters are the same as listed above for the APIs that have an asterisk. The results of this API request will contain a jobId that you then pass on to steps 2 and 3.

Basic Information

serviceNameAny service name from above.
functionNamecreateQueryJob

Responses

CodeTypeDescription
200JSONThe requested data.
401JSONOccurs for various unauthorized tasks e.g. if you didn't provide credentials in your parameters.
500JSONOccurs if an internal server error occurs. Contact Altitude Support if this occurs.
Sample parameters 
{
        "zones": [<your zones>],
        "dateRange":{
        "DateFrom": "2020-11-01",
        "DateTo": "2020-11-30"
        },
        "queryType": "getSpeedMapInfo"
}
Sample Response 
{
        "id": "c39febf6-24a6-4c0f-8e15-e43ccc95cd52",
        "status": {"state": "RUNNING"}
}

Step 2: getJobStatus

This API can be used to check if the job is done running. The request parameters are the same as listed above for the APIs that have an asterisk, but with an added parameter of "jobId", which tells the API which job status to look for. You will get the jobId in the results for the createQueryJob API request. If the job is done, you will receive a state value of "DONE" in the status object, otherwise it will be “RUNNING”.

Basic Information

serviceNameAny service name from above.
functionNamegetJobStatus

Responses

CodeTypeDescription
200JSONThe requested data.
401JSONOccurs for various unauthorized tasks, such as not providing credentials in your parameters.
500JSONOccurs if an internal server error occurs. Contact Altitude Support if this occurs.
Sample parameters 
{
        "zones": [<your zones>],
        "dateRange":{
        "DateFrom": "2020-11-01",
        "DateTo": "2020-11-30"
        },
        "jobId": "9fdf6241-4929-46ce-b3b7-f26f2de05618",
        "queryType": "getSpeedMapInfo",
        "resultsLimit": 50000
}
Sample Response 
{
        "id": "c39febf6-24a6-4c0f-8e15-e43ccc95cd52",
        "status": {"state": "DONE"}
}

Step 3: getQueryResults

Once you receive a status of "DONE" from the getJobStatus API, you can get the results using this API. The request parameters are the same as listed above for the APIs that have an asterisk, but with a few added parameters, see below.

Basic Information

serviceNameAny service name from above.StateId
functionNamegetQueryResults

Request Body

ParameterTypeDescription
jobIdStringThe ID of the job for which you want the results. This would be returned to you in step 1.
resultsLimitIntegerAn optional parameter to specify how many results you want returned per API request. If no value is provided, the API will return as many records as it can until it hits 10MB of data.
pageTokenStringWhen you get the first page of results, it will give you a pageToken to get the next page that you pass to the next getQueryResults API request and so on, until you have collected all pages.

Responses

CodeTypeDescription
200JSONThe requested data.
401JSONOccurs for various unauthorized tasks e.g. if you didn't provide credentials in your parameters.
500JSONOccurs if an internal server error occurs. Contact Altitude Support if this occurs.
Sample parameters 
{
        "zones": [<your zones>],
        "dateRange":{
        "DateFrom": "2020-11-01",
        "DateTo": "2020-11-30"
        },
        "jobId": "9fdf6241-4929-46ce-b3b7-f26f2de05618",
        "pageToken": "BFJMYXG6OYAQAAASA4EAAEEAQCAAKGQIBDPOSBIQ2CDAGIFQVYKQ====",
        "queryType": "getSpeedMapInfo",
        "resultsLimit": 50000
}
Sample response 
[{
        "SegmentId": "-1000209641098750643",
        "WayId": 491728481,
        "RoadType": "primary",
        "SegmentName": "North Decatur Boulevard",
        "CountyId": "32003",
        "CityId": "3251800",
        "SegmentIndex": 3,
        "NodeFrom": 9031210751,
        					"IsOneWay": false,
        "CardinalDirectionStartingAtNodeFrom": "N",
        "CardinalDirectionStartingAtNodeTo": "S",
        "SpeedLimit": 40,
        "Geography": "{ \"type\": \"LineString\", \"coordinates\": [ [-115.2075206, 36.2345728], [-115.2075475, 36.2353898] ] } "
}]

Canceling an Existing Query

To cancel an existing query, use the cancelQueryJob call. You can request this if you are writing an application that kicks off a query, and then you change your parameters and want to cancel the old query and run a new one. The request parameters are the same as listed in step 1 above, but with an added parameter of "jobId", which tells the API which job to cancel. You will get the jobId in the results for the createQueryJob API request.

Basic Information

serviceNameAny service name from above.
functionNamecancelQueryJob

Responses

CodeTypeDescription
200JSONThe requested data.
401JSONOccurs for various unauthorized tasks e.g. if you didn't provide credentials in your parameters.
500JSONOccurs if an internal server error occurs. Contact Altitude Support if this occurs.
Sample parameters 
{
        "zones": [<your zones>],
        "dateRange":{
        "DateFrom": "2020-11-01",
        "DateTo": "2020-11-30"
        },
        "isMetric": false,
        "jobId": "9fdf6241-4929-46ce-b3b7-f26f2de05618",
        "queryType": "getSpeedMapInfo",
        "resultsLimit": 50000
}
Sample response 
{
        "id": "c39febf6-24a6-4c0f-8e15-e43ccc95cd52",
        "status": {"state": "CANCELLED"}
}