Making an API Request

Learn how to make API requests using MyGeotab wrappers or direct POST requests, including necessary parameters and authentication details.

Every API request requires a serviceName, functionName, queryType, and other functionParameters as needed.

  • The method for all API requests is GetAltitudeData. You will be notified if this changes.

  • The APIs should be called using a POST command.

  • Parameters are case-sensitive.

  • Altitude data has a 4-day latency.

  • All times (timeFrom or timeTo) in the API request should be submitted in the local time according to the region of analysis.

You can make an API request either through MyGeotab's request wrappers, or by sending a POST request to Altitude.

Making an API Request with MyGeotab Request Wrappers

Use any MyGeotab API request wrappers available on Geotab's GitHub.

When calling the authenticate method of these wrappers, you will need to add serverName or server (depends on the wrapper you choose) as a parameter (in the same object that has your userName, database, and password) and set it to “altitudeserver.geotab.com”. After authenticating, you can use your API object to make an API request similar to the following: 


api.call("GetAltitudeData", {
	"serviceName":<serviceName>,
	"functionName":<functionName>,
	"functionParameters":{
		"queryType": <queryType>,
		...otherParams
	}
}, function(result) {
	console.log("Done: ", result);
}, function(e) {
	console.error("Failed:", e);
});

Making an API Request with a POST Request

Pass your credentials to the Altitude server to begin using the Altitude API

Make a POST request to https://altitudeserver.geotab.com/apiv1/ and pass your credentials with every request along with your other parameters.


{
	"method":"GetAltitudeData",
	"params":
	{
		"serviceName": "<serviceName>",
		"functionName": "<functionName>",
		"functionParameters":{
			"queryType": <queryType>,
			...otherParams
	},
	"credentials":{
		"database": "<your database>",
		"sessionId": "<your sessionId>",
		"userName": "<your userName>"
		}
	}
}

Obtaining a SessionId

If you decide to use the second option (make a POST request), first you need to make an authentication API request to get your session Id. You also need to ensure that you include a credentials object with every API request. Use the information received in the Altitude welcome email (username, password, and server name) to make an authentication API request to get a session Id that will be used in all subsequent API requests. Session Ids are valid for two weeks.

Basic Information

FieldValue
URLhttps://altitudeserver.geotab.com/apiv1/
MethodPOST
AuthenticationNone, public

Request Body

ParameterTypeDescription
MethodStringMust equal "Authenticate".
ParamsObjectAn object that contains "database", "userName", "password".
  • database is the database name that you receive when you sign up for the Altitude platform.
  • username is the username that you receive when you sign up for the Altitude platform.
  • password is the password that you set up when you receive the reset password email upon signing up for the Altitude platform.

Responses

CodeTypeDescription
200JSONAn object with your credentials to be used for future API requests.
401/500JSONCan be any of a variety of errors.

Sample Request Body


{
	"method": "Authenticate",
	"params":
	{
		"database": "<your database name>",
		"password": "<your password>",
		"userName": "<your user name>"
	}
}

Sample Response


[{
	"result": {
	"credentials": {
		"database": "<your database name>",
		"sessionId": "<your new session id>",
		"userName": "<your user name>"
	},
	"path": “altitudeserver.geotab.com”
	},
	"jsonrpc": "2.0"
}]