Version: 1.0
Web Service Topic / PageI. Overview
/ 1v Historical Valuations / 2
v Data Frequency / 2
v Valuation Conditions / 2
II. Web Service Security
/ 3v Logon Id and Password / 3
v IP Addresses / 4
III. Web Service Function Summary
/ 4IV. Retrieving Vehicle Values By Drilldown / 5-7
V. Retrieving Vehicle Values By UVC / 8
V. Retrieving Vehicle Specification PDF’s / 9
VI. Retrieving Trend Analysis Data
v Monthly Averages / 10
v Annual Averages / 10
VII. Web Service Messages
v Error Messages / 11v Warning Messages / 11
VIII. Web Service Transaction Counting
/ 12Section I. Overview
This section will provide you with a brief overview of the Cars of Particular Interest (CPI ) web service and all the options that are available to you when your account is setup. Subsequent sections of this document will delve into the details of each web service function, but a quick reference of general capabilities should jumpstart your efforts in integrating with the Black Book CPI web service.
First, the domain name used exclusively for web services at Black Book is www.BlackBookWS.com. This particular service was developed using the Microsoft .Net framework, so all functionality derives from the CPIWS.asmx document or at: https://www.BlackBookWS.com/CPIWS.asmx. If you clicked on the link then you should see a list of all functions included in the CPI web service. By simply adding ?WSDL onto the end of the URL you can access the web service description language, so try accessing https://www.BlackBookWS.com/CPIWS.asmx?WSDL.
Section I. Overview (continued)
We also provide a development WebService domain for use while you are in the development process. The URLs to use are as follows. Development servers do not require a Secured HTTP call:
http://www.Nationalautoresearch.com/WebServices/CPIWS.asmx.
http://www.Nationalautoresearch.com/WebServices/CPIWS.asmx?WSDL
Historical Valuations
This option can be turned on for your account to permit a historical date to be passed in for retrieving historical values. If this option is not turned on then the web service simply returns current values.
Data Frequency
The CPI data is currently published bi-monthly.
Valuation Conditions
Three vehicle conditions are included in the CPI web service:
1. Excellent Condition: Nearly perfect condition. The vehicle has usually been professionally restored to the current highest standard, but a few exceptionally well cared for originals may qualify. All components are original or are exact replacements. Most excellent cars are not driven more than a few miles per year, if at all. There are vehicles, usually due to an interesting history or special circumstances, which will sell for more than CPI's excellent figure, but these are extremely rare and would require extensive documentation.
2. Good Condition: Very nice condition. In fact, most casual observers would describe the vehicle as excellent. "Good" cars show very little wear and are driven sparingly. Many are used as weekend drivers. Many older restorations fall into this category.
3. Fair Condition: Presentable condition. Runs and drives and will pass a state inspection. Maybe be driven on a daily basis. Generally in need of a cosmetic restoration, but not a "basket case", or parts car. There are many cars on the road that fall below CPI's "fair" category, and will be priced accordingly. These are commonly referred to as "beaters" and usually not worth restoring, as the restoration costs will almost certainly exceed the value of the finished vehicle.
Section II. Web Service Security
Security for the CPI web service can be accomplished leveraging one of two methods. The first method requires that you pass in a logon id and password that was assigned to you at account setup time. The second method searches each HTTPS header for the IP address(es) that you provided at account setup time. More details concerning each method will follow.
It is also important to note that Black Book utilizes SSL or Secure Socket Layer (digital certificates) to secure the data packets transmitted between servers. In the overview section or the first section of this document you will notice that all URLs include the HTTPS designation. This measure ensures the data is encrypted and alleviates any concerns that may arise over sending the logon id and password to the web service in the first security option outlined below.
Logon ID and Password Security
This method requires the authentication information to be passed into the web service by populating the soap header with the user credentials. The CPI web service has a class defined called UserCredentials that can be instantiated and populated to gain access using this method. The sample C# code below assumes that a reference to the web service has been established and is called CPIWS.
// create web service object reference
protected CPIWS.CPIWS ws = new CPIWS.CPIWS();
// create user credentials class
protected CPIWS.UserCredentials uc = new CPIWS.UserCredentials();
…
uc.userid = “johnsmith”; // load logon id
uc.password = “smith123”; // load password
uc.producttype = "W"; // load ‘W’ for web service
uc.customer = “XXX1234” //customer identifier for segregating hit & valuation counts
ws.UserCredentialsValue = uc; // load credentials into soap header
This is all the code that is required to handle security, so that the web service can identify the requesting source and return the requested XML.
Section II. Web Service Security (continued)
IP Address Security
If you choose not to pass in the logon id and password then an IP address or IP address range can be provided at setup time, so that authentication can be done at the server level, not user level. When a web service request is received the IP address is extracted from the HTTPS header for use in authentication. And the administration system for the web service handles any number of IP addresses and ranges. To find out what your IP address is and how the web service will authenticate your server please go to the following URL: https://www.BlackBookWS.com/CPIws.asmx/IPAddress
Section III. Web Service Function Summary
This table contains a summary listing of all the web service functions and a brief description. A more detailed overview of each function will be covered in subsequent sections of this document. The namespace for the CPI web service is CPIWS.
Function Name / Overload(Y/N) / Overload Parameter / Function Description
getYears / N / Retrieve model years
getMakes / N / Retrieve makes by year
getModels / N / Retrieve models by year & make
getValues / Y / History Date / Retrieve vehicle values by year, make and model
GetUVCValues / Y / History Date / Retrieve vehicle values by UVC
getPDFSpec / N / Retrieve vehicle specification PDF
getTrendAnalysisValues / N / Retrieve trend analysis values
getIPAddress / N / Retrieve IP address for account setup
Section IV. Retrieving Vehicle Values by Drilldown
Each vehicle in the Black Book CPI database has a vehicle description made up of 3 elements: year, make and model. To retrieve vehicle values and information, the user would select a year, then a make for that year, then a model for that year and make. This process is called a drilldown.
The CPI web service uses four functions in support of the drilldown process. The function and their signatures are as follows:
1. public DataSet getYears()
Returns:
Dataset Name / modelyearsTable Name / years
Data Element Name(s) / year
2. public DataSet getMakes(string sYear)
Returns:
Dataset Name / vehiclemakesTable Name / makes
Data Element Name(s) / make
3. public DataSet getModels(string sYear,
string sMake)
Returns:
Dataset Name / vehiclemodelsTable Name / models
Data Element Name(s) / model
4. public DataSet getValues(
string sYear,
string sMake,
string sModel,
bool bFillDrilldown,
dateTime dHistoricalDate)
Returns:
Dataset Name / vehiclevaluesTable Name / values
Data Element Name(s) / (See table next page)
Section IV. Retrieving Vehicle Values by Drilldown (continued)
The table below lists all the data elements for the CPI vehicle valuation dataset.
Data Element Name / Element Descriptionyear / 4 digit year
make / i.e. Ford
model / i.e. Expedition
fair / Value of vehicle in fair condition
good / Value of vehicle in good condition
excl / Value of vehicle in excellent condition
actualdate / Date of valuation
make_cd / Numeric Make code
full_uvc / 10 character Black Book vehicle identifier
The example below illustrates how to begin the drilldown by calling the getYears function. The code was written in C#.
DataSet ds = new DataSet();
ds = ws.getYears();
All the model years will be returned in descending order. Once the user has chosen a year, the getMakes function is called as follows:
DataSet ds = new DataSet();
ds = ws.getMakes(“1963”);
All of the makes for the year indicated will be returned in alphabetic order. Similarly, the getModels function is called after the user has chosen a make:
DataSet ds = new DataSet();
ds = ws.getModels(“1963”,”Chevrolet”);
All of the models for the supplied year and make will be returned in alphabetic order. Once the user has chosen a model, the getValues function is called:
DataSet ds = new DataSet();
ds = ws.getValues( “1963”, “Chevrolet”, “Impala Wagon”,false);
Section IV. Retrieving Vehicle Values by Drilldown (continued)
bFillDrilldown
This boolean parameter for the getValues function signals the web service to populate a series of tables within the returned dataset for the vehicle description. So instead of returning one data table with the valuations, three other data tables would be returned with the years, makes, and models. Here is some sample code to retrieve the data tables after calling getValues with the bFIllDrilldown paramter set to true:
DataTable dtValues = ds.Tables[0];
DataTable dtYears = ds.Tables[1];
DataTable dtMakes = ds.Tables[2];
DataTable dtModels = ds.Tables[3];
dHistoricalDate (optional parameter)
If the ability to query historical values was turned on for your account by a Black Book systems administrator then a date in the past can be entered to retrieve historical values. All the same data elements are returned with the values set as of that date. The history database goes back to October of 1999, so any effort to query before that date will result in an error.
Section V. Retrieving Vehicle Values by UVC
An excellent way of retrieving vehicle values is to leverage the Black Book UVC or Universal Vehicle Code. This 10 character alphanumeric code uniquely identifies each vehicle. The full UVC code can be broken down as follows:
1. Year – 4 characters (i.e. 1957)
2. Make Code – 3 characters (i.e. 720 for Pontiac)
3. UVC Code – 3 characters (i.e. P01 for Star Chief Sedan)
So in looking at the sample above the full UVC would be 1957720P01 and would retrieve the 1957 Pontiac Star Chief Sedan. If every time a vehicle is retrieved and the full UVC was saved in your database, then subsequent vehicle value retrievals would be expedited with a one-to-one UVC lookup.
The function signature is as follows:
public DataSet getUVCValues(
string sUVC,
bool bFillDrilldown,
dateTime dHistoricalDate)
* dHistoricalDate is an optional parameter. See the explanation in the section “Retrieving Vehicle Values by Drilldown”.
Example:
ds = ws.getUVCValues("1957720P01", true);
Returns:
Dataset Name / vehiclevaluesTable Name / values
Data Element Name(s) / (See table of data elements in the section “Retrieving Vehicle Values by Drilldown”
Section VI. Retrieving Vehicle Specification PDF’s
Black Book has not only been printing valuation guides for over fifty years, but also vehicle specification guides. Each year, PDF files are generated for each vehicle model that provides a complete snapshot of the vehicle specifications. These specifications include standard equipment, vehicle options, etc. These PDF files can be retrieved using the CPI Web service.
The function signature is as follows:
public byte[] getPDFSpec(string sYear, string sMake, string sModel,
string sJustCheck)
The year, make and model parameters are self explanatory, and the sJustCheck parameter should be set to either “Y” or “N”. A value of “Y” indicates that you don’t want to retrieve the PDF file, you just want to know if it exists for the specified vehicle. This might be handy if you want to show a link on your user interface to retrieve the PDF file. If you know that the file doesn’t exist for a particular vehicle, you would not show the link. If sJustCheck is set to “Y”, then an empty byte array will be returned, and the code and message in the soap header will reflect whether the file exists or not. See Web Service Messages.
The returned stream of data is a byte array, so you will need to load a byte array and then save the stream off as a PDF file. The C# code below provides an example of how the function call can be made and how the byte stream can be saved as a PDF file.
byte[] bytPDF = ws.getPDFSpec("1963", "Chevrolet",”Impala Wagon”,”N”);
MemoryStream memStream = new MemoryStream(bytPDF);
FileStream fileStream = new FileStream(path + fileName,
FileMode.Create);
memStream.WriteTo(fileStream);
memStream.Close();
fileStream.Close();
fileStream = null;
memStream = null;
Section VII. Retrieving Trend Analysis Data
If this data type was turned on for your account then you will have the option of retrieving monthly or annualized vehicle values. If the frequency parameter is set to “M” then up to 24 months of values or twenty-four rows of data can be retrieved. If the frequency parameter is set to “A” for annualized then up to 5 years of values or 5 rows of data can be retrieved. Both options leverage a start and end date in selecting the number of months or years.
The function signature is as follows:
public DataSet getTrendAnalysisValues( string sYear,
string sMake,
string sMoldel,
string sAnnualOrMonthly,
DateTime dStartDate,
DateTime dEndDate)
The getTrendAnalysisValues function returns the following dataset and elements.
Trend Analysis Dataset ElementsData Element Name / Element Description
Frequency / “A” for Annual or “M” for monthly
trend_year / The year of the valuation
trend_month / The month of the valuation as a number (1-12)
fair / Value of vehicle in fair condition
good / Value of vehicle in good condition
excl / Value of vehicle in excellent condition
Section VIII. Web Service Messages