Making raw requests to the CIS Automotive API

Introduction

Our easy to use API makes your automotive market's data available to you. This guide is intended for people with at least some programming background and will include code snipits that can be used as a starting point. Detailed endpoint specific documentation is available here and more use case examples are available here.

Our python library cisapi requires Python 3.6 or higher. The python scripts below are written with Python 3.7, but many of them will work with other versions of python. If you don't have python installed you can get it here, or use the examples in the language agnostic guide if you would rather use a different language.

Our API is also available for general use from the following third parties:

Making your first request

We recommend using our python library cisapi to make API calls. It handles all the API authentication and implimentation details for you for both RapidAPI and direct calls to our API, but we understand you may be more comfortable using a different language like Ruby or Java. This guide goes over the implimentation details needed to make API requests from any programming language.

Our API is a stateless REST API that uses JSON Web Tokens (JWT) for authentication. Our first request will be to authenticate against the API with our APIKey and APIKeyID so we can retrieve our JWT for all the other requests. Your APIKey and APIKeyID can be retrieved from your account info. If you do not have an account yet you can sign up here or use one of our third party providers above.

The general workflow when using the CIS Automotive API is as follows:

If you are accessing our API through RapidAPI, their system will transparently add the JWT for you, but you will still need to provide your RapidAPI key to them. Below is a simple example of the getModels endpoint for RapidAPI users.

#RapidAPI
import requests

url = "https://cis-automotive.p.rapidapi.com/getModels"

querystring = {"brandName":"Toyota"}

headers = {
    'x-rapidapi-host': "cis-automotive.p.rapidapi.com",
    'x-rapidapi-key': "YOUR-RAPID-API-KEY-HERE"
    }

response = requests.request("GET", url, headers=headers, params=querystring)
#final url: "https://cis-automotive.p.rapidapi.com/getModels?brandName=Toyota"

print(response.text)

We reccomend you first create a file to store your API credentials securely. Our API Quick Start Guide goes over this process.

We will now retrieve our JWT from the API with the following Python script. It uses the third party library requests to simplify the http requests. If you don't have it installed already your can install it with pip "pip install requests"

Python Example

#import all the libraries we need
import requests
import configparser

#define our consts
apiURL="https://api.AutoDealerData.com/"

#read our credentials from the file
parser=configparser.ConfigParser()
parser.read("CIS_API_CREDS.txt")
apiKey=parser["default"]["API_KEY"]
apiID=parser["default"]["API_ID"]

#make get request to "/getToken" endpoint
resp=requests.get(apiURL+"getToken"+"?apiKey="+apiKey+"&apiID="+apiID)
#final url: https://api.AutoDealerData.com/getToken?apiKey=YOUR_API_KEY&apiID=YOUR_API_ID

print(resp.json())
jwt=resp.json()["token"]
print("Your token is: "+jwt)
validFor=resp.json()["expires"]-resp.json()["createdOn"]
print("The token is valid for "+str(validFor/3600)+" hours "
    +"and you will need to get a new one after that time.")

Alternitively we can make the request with curl.

Curl Example

curl -X GET "https://api.AutoDealerData.com/getToken?apiID={API_ID}&apiKey={API_KEY}" -H  "accept: application/json"

We now have our token value saved in the "jwt" variable. We will need to use this value in future API calls for the next 24 hours. After that time the token expires and we will need to get a new one like we just got the current one.

Retrieving data from the API

Now that we have authenticated we can access the other endpoints. The full endpoint documentation is available here, but for now we're going to get statistics on the sale price of vehicles for an arbitrary brand and region. We first need to get the list of brands and the list of regions. Then we can use those lists to request the sales data we want.

Python Example

#make get request to "/getBrands" and "/getRegions" endpoints
brandsResp=requests.get(apiURL+"getBrands"+"?jwt="+jwt)
regionsResp=requests.get(apiURL+"getRegions"+"?jwt="+jwt)

print(brandsResp.json())
print(regionsResp.json())

brandNames=brandsResp.json()["data"]
regionNames=regionsResp.json()["data"]

#we can loop through these like any list
for i in range(5):
    print(brandNames[i])
for brand in brandNames[5:10]:
    print(brand)

We can also use curl to request the data.

Curl Example

curl -X GET "https://api.AutoDealerData.com/getBrands?jwt={JWT}" -H  "accept: application/json"
curl -X GET "https://api.AutoDealerData.com/getRegions?jwt={JWT}" -H  "accept: application/json"

We have now retrieved a list of the brand names and a list of the region names from the API using an authenticated endpoint. We can take that list and use it to access data from more endpoints that require a specific brand and region name.

Python Example

#for this example we will use a hard coded brand and region name
brandName="Chevrolet"
regionName="REGION_STATE_CA"

#make get request to "/salePrice" endpoint
saleResp=requests.get(apiURL+"salePrice"+"?jwt="+jwt+
    "&brandName="+brandName+"&regionName="+regionName)

print(saleResp.json())
salesData=saleResp.json()["data"]

#for this endpoint salesData is a list of dictionaries
for sale in salesData:
    for key in sale.keys():
        print(key+": "+str(sale[key]))
    print("")

Like before, we can also use curl to request the data.

Curl Example

curl -X GET "https://api.AutoDealerData.com/salePrice?jwt={JWT}&brandName=Chevrolet&regionName=REGION_STATE_CA" -H  "accept: application/json"

We've now retrived data from an authenticated endpoint using data provided by a seperate endpoint. With this access pattern we can make full use of the API and pull any available data from it. You can view the full endpoint documentation here and here to see what other data you can pull.

Full Example Code

The above code examples are provided here for your convenience.

#import all the libraries we need
import requests
import configparser

#define our consts
apiURL="https://api.AutoDealerData.com/"

#read our credentials from the file
parser=configparser.ConfigParser()
parser.read("CIS_API_CREDS.txt")
apiKey=parser["default"]["API_KEY"]
apiID=parser["default"]["API_ID"]

#make get request to "/getToken" endpoint
resp=requests.get(apiURL+"getToken"+"?apiKey="+apiKey+"&apiID="+apiID)
#final url: https://api.AutoDealerData.com/getToken?apiKey=YOUR_API_KEY&apiID=YOUR_API_ID

print(resp.json())
jwt=resp.json()["token"]
print("Your token is: "+jwt)
validFor=resp.json()["expires"]-resp.json()["createdOn"]
print("The token is valid for "+str(validFor/3600)+" hours "
    +"and you will need to get a new one after that time.")

#make get request to "/getBrands" and "/getRegions" endpoints
brandsResp=requests.get(apiURL+"getBrands"+"?jwt="+jwt)
regionsResp=requests.get(apiURL+"getRegions"+"?jwt="+jwt)

print(brandsResp.json())
print(regionsResp.json())

brandNames=brandsResp.json()["data"]
regionNames=regionsResp.json()["data"]

#we can loop through these like any list
for i in range(5):
    print(brandNames[i])
for brand in brandNames[5:10]:
    print(brand)

#for this example we will use a hard coded brand and region name
brandName="Chevrolet"
regionName="REGION_STATE_CA"

#make get request to "/salePrice" endpoint
saleResp=requests.get(apiURL+"salePrice"+"?jwt="+jwt+
    "&brandName="+brandName+"&regionName="+regionName)

print(saleResp.json())
salesData=saleResp.json()["data"]

#for this endpoint salesData is a list of dictionaries
for sale in salesData:
    for key in sale.keys():
        print(key+": "+str(sale[key]))
    print("")