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.

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
  • 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_with_your_just_web_token_here'

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.

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.

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.

{
  "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. If you try, you will get an error. Have we no fear, we love JavaScript developers too! You have two options:

  1. Proxy your requests to a server-side language of your choice.
  2. Sign-up for an account with RapidAPI (it's free) and email support [email protected] with your CarAPI accounts email address and your RapidAPI username. We will take it from there.

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.