Zonar API Introduction

Security

HTTPS (Hypertext Transfer Protocol Secure) and HTTP (Hypertext Transfer Protocol) are both protocols used for transferring data over the internet. However, HTTPS adds an extra layer of security by encrypting the data being transferred. This means that any sensitive information, such as login credentials or personal information, is protected from being intercepted by malicious actors. For this reason, it is highly recommended to use exclusively HTTPS in API calls to ensure the security and privacy of the data being transmitted.

Structure

Zonar’s API calls take the form of a string of characters that look like a URL. The following is an example of a Zonar API call that returns the current location of all assets:

https://omi.zonarsystems.net/interface.php?customer=zzo2544&username=zonar&password=secret.pw.2019&action=showposition&operation=current&format=xml&version=2&logvers=3.3

When integrators write their software, this URL + call will most likely be constructed and fired off from within their program. You may also run individual calls by entering the URL in a browser window as if navigating to a website. This is often the best method for quickly troubleshooting an API call.

Let’s break down the previous call:

https://omi.zonarsystems.net/interface.php? – This is how all API calls should begin. You may come across older documentation that places the customer account code as the domain prefix -- for example, https://zzo2544.zonarsystems.net[…]. While this is valid, for analytics reasons we are now requesting that integrators specify their target account through the customer parameter, instead of as the subdomain.

customer=zzo2544&username=zonar&password=secret.pw.2019 – These parameters define which GTC account code is being targeted and provide credentials to authenticate. The username must exist in the target’s GTC account. It’s important to note that when a new user is created in GTC, they are given an email address, password, and username. The email address is used to log in to GTC, but the username is used to access the API/OMI. Most of the time, the user will use their same password for GTC and API access. However, it is possible that these two passwords become different. Refer to Admin Users and note the difference between Single Sign-On and API Sign-On passwords.

&action=showposition&operation=current – These are mandatory parameters that "define intent". These tell the API what it is being asked to do. Many API calls will fall under the same action but have different operations. Here, we are making an API call that has the showposition action and the current operation. For a user to be able to perform a specific action, they must have that permission enabled in GTC. Review the list of permissions in Admin Users. Notice that each permission is named identically to OMI actions. Look for the showposition action and note which GTC reports it enables. This permission is required to make the API call we’re dissecting.

&format=xml&version=2&logvers=3.3 – These additional parameters provide the API information about which data to return and in what format. The Developer Documentation pages are the best source to understand which parameters are required/optional and what different parameter values do. For example, logvers=3.3 adds the GPS odometer offset value to the returned odometer value. If we were to specify logvers=3.5, the <fuel_counter>, <fuel_level>, <avg_rpm>, and <source> elements would be included in the returned XML file.

Limitations

Integrators usually develop their applications to make regular API calls to Zonar’s servers. It’s important that they do not make calls at a rate that exceeds the rate data is returned, otherwise they will experience dropped connections. In other words, if a call takes two seconds to return, and they’re making the call every second, the solution will fail. There are a few factors that affect the amount of time it takes for an API to return data:

• Size of the GTC account
• Range of data within the account being requested (for example, the entire fleet versus a single location versus a single asset)
• Time range of requested historical data

Troubleshooting

Typically, the first step when troubleshooting API calls is to obtain an exact copy of the API URL string being called. Once this has been provided, you should copy/paste it into your browser in an attempt to reproduce the error. Returned error messages usually provide some hint into the issue.

• Does the call return a permissions error? If so, the username making the call needs to have that permission enabled in GTC.
• Is the user failing to authenticate? Check the supplied username/password combination. Reset the API password in GTC (not the SSO password). If this still doesn’t fix the issue, check the Failed Logins page in Admin Console to ensure that the user hasn’t been locked out of the account. This can easily happen if an integrator or customer runs a looping script with the wrong credentials.
• Check to make sure the URL has all required parameters (customer, username, password, action, operation). Read the individual call’s documentation page to ensure that all other required parameters are being included (this is also usually revealed in the browser error message).
• If there are starttime and endtime parameters, ensure that their values are in the correct format (usually epoch). Go to an epoch conversion site (epochconverter.com is a popular one) and convert the integrator-supplied values into human readable format. Does this time range make sense? Does it fall within the appropriate scope outlined in the documentation?
• Are there any optional parameters being passed that may filter or limit the returned data? Many API calls have parameters that filter by LOI (location of interest, more commonly known as zone or geofence) or Location.
• Unknown asset/driver/user – This usually occurs if the integrator is including a target parameter on something that doesn’t exist in the GTC account. Be sure to check the reqtype parameter as well (which specifies how ‘target’ gets defined).