Getting started with 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

Our API is a stateless REST API and our Python library cisapi creates easy to use python bindings for our API endpoints. You can install it with

pip install cisapi

If you would like to use our API with another language you can read our language agnostic guide.

We reccommend creating a configuration file to store your API keys so that it stays out of your source code. Create a file in your workspace named "CIS_API_CREDS.txt" and place your API credentials in it like this. If you are using RapidAPI to access our API leave the API_ID value blank and use your RapidAPI key for the API_KEY value.

[default]
API_KEY=YOUR_API_KEY_WITHOUT_QUOTES
API_ID=YOUR_API_ID_WITHOUT_QUOTES

If you are accessing the API directly from us you must get your API keys from your account page, if you are using RapidAPI you must get your API key from them. Once logged into RapidAPI you can go to the endpoint definitions and retrieve your "x-rapidapi-key" from the example's request headers. If you do not have an account yet you can sign up here or use one of our third party providers above.

Retrieving data from the API

Now that we have the cisapi library installed and our config file created in our working directory, we can access the API 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

from cisapi import CisApi
api=CisApi()
#api=CisApi(apiKey="your key", apiKeyID="your key id") # load without config file
#api=CisApi(configFileName="yourConfigFile.txt") # load with a non default config file name

#api.useRapidAPI=True #set true if using RapidAPI as your provider

#these are json objects with some metadata keys
#and a "data" key with the data we requested
brands=api.getBrands()
regions=api.getRegions()

print(brands)
print(regions)

brandNames=brands["data"]
regionNames=regions["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 have now retrieved a list of the brand names and a list of the region names from the API using the cisapi library. 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=api.salePrice(brandName, regionName)

print(saleResp)
salesData=saleResp["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("")

We've now retrived data from an 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.

from cisapi import CisApi
api=CisApi()
#api=CisApi(apiKey="your key", apiKeyID="your key id") # load without config file
#api=CisApi(configFileName="yourConfigFile.txt") # load with a non default config file name

#api.useRapidAPI=True #set true if using RapidAPI as your provider

#these are json objects with some metadata keys
#and a "data" key with the data we requested
brands=api.getBrands()
regions=api.getRegions()

print(brands)
print(regions)

brandNames=brands["data"]
regionNames=regions["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=api.salePrice(brandName, regionName)

print(saleResp)
salesData=saleResp["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("")