CarAPI Documentation

Developer friendly documentation for the developer friendly vehicle API.

Documentation is available in other formats too

Documentation is available in Swagger, Redoc, Postman and OpenAPI.

If you’re a PHP developer, be sure to check out our PHP SDK.

Getting Started

CarAPI accepts the application/json response format (mimetype)

Note

If no Accepts header is specified in your request the response Content-type will default to application/json. You should add an accept mimetype header to all your requests such as Accepts: application/json to future-proof your application.

Response Codes

All valid requests will return an HTTP 200. Your application should have exception handling in place to handle various non HTTP 200 codes such as, but not limited to:

• 400: Your request was invalid, generally the error message should tell what is wrong with your request.
• 401: Authentication failed.
• 404: The data you requested could not be found.
• 405: Wrong HTTP Method was used.
• 429: Too Many Requests. You exceeded the maximum requests allowed in a minute or a day.
• 500: The server encountered an issue, please report these errors to support.
• 503: Typically, the server is undergoing maintenance. This should be very temporary.

Authentication

You can begin developing immediately with CarAPI without authentication, but to unlock all data you must subscribe and send a valid JSON Web Token (JWT) along with your request. To request a JWT you must first sign up and then generate an API Secret from your user dashboard.

Next send an HTTP POST request to /api/auth/login:

curl -X 'POST' \
  'https://carapi.app/api/auth/login' \
  -H 'accept: text/plain' \
  -H 'Content-Type: application/json' \
  -d '{
    "api_token": "your_api_token",
    "api_secret": "your_secret"
  }'

Now include the JWT in all your requests:

curl -X 'GET' \
  'https://carapi.app/api/models/v2' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer replace_this_with_your_jwt'

Remember to request a new JWT after paying for your subscription

If your JWT was created before you became a paying customer, you will need to regenerate a JWT. Only after creating a new JWT will it contain your new subscription status.

More on JWTs

Your JWT should be kept secure and confidential. It’s also important to cache your JWT so you don’t have to request a new one on each request (this is bad for performance). When re-using JWTs be sure to check the expiration and renew as needed.

Your JWT will be a very long base64 encoded string that contains three parts separated by periods: a header, payload, and signature.

Payload

The middle piece, the payload, is the only portion of the JWT you need to worry about when integrating with CarAPI. After the payload has been base64 decoded it becomes a standard JSON string that will look something like this:

{
  "iss": "carapi.app",
  "sub": "56e9c7cc-e1db-4f41-8b9a-e7857d750761",
  "aud": "56e9c7cc-e1db-4f41-8b9a-e7857d750761",
  "exp": 1698276870,
  "iat": 1697672070,
  "jti": "12cdc9c5-2c2c-4dda-a570-359608275213",
  "user": {
    "subscribed": true,
    "subscription": "starter",
    "rate_limit_type": "soft"
  }
}

The properties in the decoded payload are called “claims” per the JWT standard.

Registered Claims

You can expect registered claims in all JWT tokens regardless of who is providing them. Some of these claims such as expiration (exp) are required and important to understand while others are less important or not required.

• exp: (int) When this JWT will expire as a unix timestamp. If the current time in America/New_York (EST) is greater than this value your JWT will no longer work and the API will return a 401 error. This is 7 days from creation, but that value could change so it’s important that you validate your JWT is not expired before each request. If it is, you must generate a new one.
• iss: (string) This should always be "carapi.app", you don’t need to do anything with this.
• iat: (int) The time your JWT was created at as a unix timestamp. You don’t need to do anything with this.
• jti: (string) You don’t need to do anything with this.
• sub: (string) You don’t need to do anything with this.
• aud: (string) You don’t need to do anything with this.

Learn more about JWTs

jwt.io has a free JWT decoder and many resources on JWTs. You can read more about registered claims and the JWT spec in the official RFC.

Private Claims

These are application-specific properties added by API providers such as CarAPI.

• user.subscribed: (bool) Whether you have an active subscription.
• user.subscription: (string|null) The name of your subscription plan if any.
• user.rate_limit_type: (string) Whether you have hard rate limiting or soft rate limiting enabled.

Header and Signatures

The JWT has three total parts. You don’t need to worry about the other two. The first piece, the header, is metadata used to identify the hashing algorithm. The last piece, the signature, is used to verify the JWT was not tampered with. There are scenarios where these may be important to API clients, but it’s not something you need to worry about to securely and successfully integrate with CarAPI.

Cross Origin Requests (CORS)

CarAPI does not support CORS requests. You will need to use a server-side language such as NodeJS, Python, or PHP to connect into the API. We have put together a sample proxy built in NodeJS that can be used as a starting point: https://github.com/car-api-team/nodejs-proxy-example

Caching Data

Caching data is permitted and a good way to avoid round trips for frequently accessed data. If you decide on a caching solution, it’s important to keep your cached data up to date. Most endpoints will return a modified timestamp. Say for instance you have a nightly or monthly process which checks for data changes to models:

curl -X 'GET' \
  'https://carapi.app/api/models/v2?json=[{"field":"modified","op":">=","val":"2023-08-01"}]' \
  -H 'accept: application/json'

The above request will return all models that were modified on or after 2023-08-01. Please consult the API documentation for other endpoints which support the modified timestamp.