[

](https://www.ituran.com)

# Welcome to the Ituran API Documentation ----- > ## Getting Started #### To get started choose Ituran API version on the left menu. If you have doubt which version you are running [contact us](https://ituran.co.il/ituranfront/about/contact-us/) ----- > ## What is an API? An Application Programming Interface (API) is provided by a service or program so that others may use the features and functions of the system.
APIs are like a contract that describes how a consumer/client will make requests of the system, and what they will receive in return.
An API defines the means by which the consumer of the API invokes functions and receives data in return from the provider of the API.
In short, it's a set of rules that lets programs talk to each other, exposing data and functionality across the internet in a consistent format. The URLs given in the Ituran documentation represent various resources - any information or content accessed, which can be returned as **JSON**.
Often, resources have one or more methods that can be performed on them over HTTP, like GET, POST, PUT and DELETE. > In this case, Ituran clients make use of our API to return information from the Ituran data sets belonging to their company.
> You can only reach and see *only* the data which applies to your company and account.
> **Ituran takes security very seriously.** ----- > ## General concepts using the Ituran API 1. Learn about common formats of API requests, responses and errors. 2. Get familiar with the Ituran API authentication powered by industry-standard JSON Web Tokens (JWT).
(If you are not familiar with the JWT standard, please see: [JWT @ Wikipedia](https://en.wikipedia.org/wiki/JSON_Web_Token)
and for a deep dive please see: [JWT: The Complete Guide to JSON Web Tokens](https://blog.angular-university.io/angular-jwt/) 3. Make your first call to the Ituran API. 4. Understand the **rate limits** for the Ituran API. 5. Browse through a collection of available data types and operations in Resources section. 6. Become familiar with the wealth of information which you can recieve by making specific, generated calls to the API. ----- > ## Endpoint conventions As mentioned above, **[endpoints](#endpoints)** are described with an HTTP method and a path.
**Example:**
`GET /api/v1/vehicles`
Prepend your Ituran URL to the path to get the full endpoint URL.
If your Support URL is https://api.ituran.com, then use the following endpoint URL.
**Example:**
`https://api.ituran.com/api/v1/vehicles`
Curly braces, {}, in the path indicate a placeholder value that you must replace.
**Example:**
`GET /api/v1/vehicles/{license_plate}`
The body of requests and responses for each resource is described in a JSON format table.
Each table lists a resource's properties, their data types, whether or not they're read-only, whether or not they're required, and descriptions. ----- > ## API Terminology & Parameters Dictionary Ituran Terminolgy can get overwhelming for a new user - or even for experienced ones :) - due to the number of parameters, variable and naming conventions used.
In each version you will find a table aims to provide a brief explanation of common parameters one might encounter in the process. ----- > ## Examples For cURL The [examples](#it-examples) in the docs are cURL statements.
You can run the statements on a command line to try out different API requests.
To learn more, see Installing and using cURL.
In Windows, you'll need to modify some of the examples in the docs to make them work. See Using cURL in Windows. If you use a password to authenticate your curl requests, make sure to escape any special characters in the password.
**Example:**
`pa$word` becomes `pa\$\$word` --> See this post on [StackExchange](https://unix.stackexchange.com/questions/270977/what-characters-are-required-to-be-escaped-in-command-line-arguments) for more information. You can also use the Ituran API console to try out different requests. The examples use basic authentication requiring an Ituran username and password.
Make sure to recieve a username and password for access from the Ituran Support admin interface. ----- > ## Security and Authentication Ituran uses JSON Web Tokens (JWT) for verification.
You must be a **verified user** to make API requests.
This verification always requires your Username and Password (UN & PW).
You can authorize against the API using a JWT token recogonized and authorized by the Ituran system.
The process of registering within the API system will also make sure you get a **valid** JWT token. Cross-origin resource sharing (**CORS**) is a mechanism that allows restricted resources on a web page to be requested from another domain outside the domain from which the first resource was served.
Client-side CORS requests are supported if the request is authenticated with a JWT access token.
**You are responsible for the implementation of CORS within your code.** ### JWT The Ituran API supports JWT authorization flows.
JWT's also permit client-side API requests.
See Making cross-origin [CORS](#cors), browser-side API requests in the Ituran API guide.
In your requests, specify the access token in an Authorization header as follows:
`Authorization: Bearer {access_token}`
**Example:**
`Authorization: Bearer gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo`
If you use curl to test different endpoints, you can use the following format: ```bash curl https://api.ituran.com/api/v1/vehicles \ -H "Authorization: Bearer gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo" ``` ----- ### SSL requirements The Ituran API is an SSL-only API, regardless of how your account is configured.
All connections to the Ituran API must support the TLS 1.2 protocol (for a proper understanding of TLS 1.2 Protocol please see [here](https://en.wikipedia.org/wiki/Transport_Layer_Security#TLS_1.2)).
Connections to the API must also support the SNI extension to TLS.
If you connect to Ituran through a client library, make sure it supports both TLS 1.2 and SNI. ----- ### Rate limits The Ituran API is rate limited.
Only allow a certain number of requests are allowed per minute depending on your plan and the endpoint.
Ituran reserves the right to adjust the rate limit for given endpoints to provide a high quality of service for all clients.
As an API consumer, you should expect to be able to make the following number of requests per minute per Ituran Support account.
For a general understanding of **Rate Limits** see [here](https://en.wikipedia.org/wiki/Rate_limiting) As well, each endpoint can have its own rate limit.
For example, there is a rate limit of 30 updates to the same ticket by the same agent within a 10-minute window.
See Endpoint-specific rate limits below. You can compare your activity in the last 24 hours with the Core API against your rate limit. You can use the following response headers to confirm the account's current rate limit and monitor the number of requests remaining in the current minute: ``` X-Rate-Limit: 700 X-Rate-Limit-Remaining: 699 X-Rate-Limit-Reset: 92 ``` * **X-Rate-Limit** indicates how many calls your application may make per time window. * **X-Rate-Limit-Reset** indicates when the current window ends, in seconds from the current time. * **X-Rate-Limit-Remaining** indicates how many calls you have remaining in this window. Notwithstanding the limits specified in this document,
*the system might still limit requests if it detects an unusual spike in requests from all sources for the account, including internal product requests*.
This can happen in a denial-of-service attack, for example.
The account-wide limit is **100,000** requests per minute. If the rate limit is exceeded, the API responds with a [HTTP 429 Too Many Requests response code](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#4xx_Client_errors) and a body that details the reason for the rate limiter kicking in.
The response has a Retry-After header that tells you for how many seconds to wait before retrying.
You should anticipate this in your API client for the smoothest possible ride.
See Best practices for avoiding rate limiting. ----- > # Request format The Ituran API is a JSON API.
You must supply a `Content-Type: application/json` header in PUT and POST requests.
You must set an `Accept: application/json` header on all requests. The documented JSON properties for this API are ~**case sensitive**.
For example, the following `POST /api/v1/oauth/token` won't work because password property is capitalized: ``` json { "username": "user", "Password": "pa$$word" } ``` To learn more on the JSON format, see the following: 1. [JSON - Wikipedia](https://en.wikipedia.org/wiki/JSON) 2. [What is JSON? A better format for data exchange](https://www.infoworld.com/article/3222851/what-is-json-a-better-format-for-data-exchange.html) 3. [Working with JSON](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Objects/JSON) ----- > # Response format The Ituran API responds to successful requests with HTTP status codes in the 200 or 300 range.
When you **create or update** a resource, the API renders the resulting JSON representation in the response body and sets a Location header pointing to the resource.
**Example:**
`Status: 201 Created Location` ``` json { "data": { "license_plate": 1313113, "battery": 1, "oil": 1, "engine_heat": 1, "brakes": 1, "lights": 1 } } ``` Responses may have the status codes described in the following sections.
Please see [here](https://www.wikiwand.com/en/List_of_HTTP_status_codes?wprov=srpw1_1) for a complete list. ----- > ## General HTTP Response Rules: All HTTP response status codes are separated into five classes or categories.
The first digit of the status code defines the class of response, while the last two digits do not have any classifying or categorization role.
There are five classes defined by the standard: * 1xx informational response - the request was received, continuing process * 2xx successful - the request was successfully received, understood, and accepted * 3xx redirection - further action needs to be taken in order to complete the request * 4xx client error - the request contains bad syntax or cannot be fulfilled * 5xx server error - the server failed to fulfill an apparently valid request A complete list of all HTTP Response Codes is available [here](https://www.wikiwand.com/en/List_of_HTTP_status_codes) and [here](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes?oldformat=true).
When building an API client, we recommend treating any 500 status codes as a warning or temporary state.
However, if the status persists and we don't have a publicly announced maintenance or service disruption, contact us at . If submitting a ticket to Support, provide the Ituran-Request-Id header included in the HTTP response.
This helps the Support team track down the request in the logs more quickly. > ## Pagination By default, most list endpoints return a maximum of 100 records per page.
You can change the number of records on a per-request basis by passing a page_size parameter in the request URL parameters.
**Example:**
`page_size=50`
**However, you cannot exceed 100 records per page on most endpoints.** When the response exceeds the per-page maximum, you can paginate through the records by incrementing the page parameter.
**Example:**
`page_number=3`
List results include pagination metadata in the response body for easier navigation: ```json { "metadata": { "pagination": { "page_number": 4, "page_size": 31, "total_count": 96, "page_count": 4 } }, "vehicles": [ ... ] } ``` ----- > ## Feedback Your feedback does matter. [Let us](https://ituran.co.il/ituranfront/about/contact-us/) know what you want to see from the Ituran API. ----- .