Skip to content

Developer Documentation

image

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 following response formats (mimetypes):

  • application/json (recommended)
  • application/ld+json
  • application/hal+json

Default response type is application/json

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 [email protected].
  • 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' \
  'http://localhost:8080/api/models' \
  -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 its 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 anything with this.
  • sub: (string) You don't need to anything with this.
  • aud: (string) You don't need to anything with this.

Learn more about JWTs

Did you know 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

We mentioned the JWT has three total parts earlier. 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.

Sorting

Check Swagger for which fields can be sorted, for example, you can sort the models endpoint by name in either ascending or descending order:

curl -X 'GET' \
  'https://carapi.app/api/models?sort=name&direction=desc' \
  -H 'accept: application/json'

Pagination

Endpoints offering pagination will indicate this in their responses. Most endpoints default to 100 results per page but can go up to 1000 per page. This can be set using the limit query parameter. 

{
  "collection": {
    "url": "/api/trims",
    "count": 100,
    "pages": 688,
    "total": 68754,
    "next": "/api/trims?page=2",
    "prev": "",
    "first": "/api/trims",
    "last": "/api/trims?page=688"
  },
  "data": []
}

Example: 

curl -X 'GET' \
  'https://carapi.app/api/models?page=2&limit=50' \
  -H 'accept: application/json'

Complex Filters

In addition to standard HTTP GET query parameters, many endpoints offer the json query parameter. This takes an array of filter objects expressed as JSON. For example:

[
    {
        "field": "make",
        "op": "in",
        "val": [
            "Ford",
            "Acura"
        ]
    },
    {
        "field": "year",
        "op": ">=",
        "val": 2010
    }
]

Can be included in your request to /api/models: 

curl -X 'GET' \
  'https://carapi.app/api/models?json=[{"field": "make", "op": "in", "val": ["Ford", "Acura"]}, {"field": "year", "op": ">=", "val": 2010}]' \
  -H 'accept: application/json'

Check Swagger for a full list of query options

Swagger documentation contains all possible filters.

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?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.

Vehicle Attributes

Certain vehicle attributes such as engine type and engine type are enumerated. That is, their values can only be members of a well-defined list. You can query available vehicle attributes and use these to improve your searches.