Web Service Topic

/ Used Car Web Service Documentation

Version: 4.0

Web Service Topic / Page(s)

I. Overview

v  Data Markets / 2
v  Data Frequencies / 3
v  Data Types / 3
v  Valuation Conditions / 4

II. Web Service Security

v  Logon Id and Password / 4-5
v  IP Addresses / 5

III. Web Service Function Summary

/ 6
IV. Retrieving Vehicle by Drilldown / 7-14
V. Retrieving Vehicle by VIN / 14-19
VI. Retrieving Vehicle by VIN and UVC / 20-22
VII. End of Term Value / 22
VIII. Applying Adjustments to Values
v  Retrieving Mileage Adjustments / 23-29
v  Retrieving Add/Deducts
v  Regional Adjustments
v  Fifty Percent Rule
v  U.S. Valuation Adjustments
v  Canadian Valuation Adjustments

IX. Retrieving Vehicle Photographs

/ 30
X. Retrieving Vehicle Specification PDF’s / 31
XI. Retrieving Trend Analysis Data / 32-33

XII. Standard Equipment

/ 34

XIII. Colors

/ 35

XIV. Web Service Messages

/ 36-37

XV. Web Service Transaction Counting

/ 38

Appendix ‘A’ – Vehicle Classes

/ 39

Appendix 'B' - US Valuation Schema

/ 40-43

Appendix ‘C’ - Canadian Valuation Schema

/ 44-48

Section I. Overview

This section will provide you with a brief overview of the used car 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 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 UsedCarWS.asmx document or at: https://www.BlackBookWS.com/UsedCarWS.asmx. If you clicked on the link then you should see a list of all functions included in the used car 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/UsedCarWS.asmx?WSDL.

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/usedcarws.asmx

http://www.nationalautoresearch.com/webservices/usedcarws.asmx?WSDL

Now that we know where to access the web service let’s take a closer look at some of your account setup options. These topics fall into five categories; (1) data markets, (2) historical valuations, (3) data frequencies, (4) data types, and (5) valuation conditions.

Data Markets

1.  United States

2.  Canadian

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.

Return To Table of Contents

Section I. Overview (continued)

Data Frequencies

1.  Daily (default & U.S. only)

2.  Weekly (U.S. only)

3.  Monthly (U.S. only)

4.  Bi-weekly (Canadian only)

5.  All – can change a frequency code for web service calls to pull data based on any data publish frequency.

Data Types (can only be setup by a Black Book system administrator)

Any combination of data types can be turned on when your account is setup. And it takes two minutes to change the settings later if other information is required.

1.  All data types

2.  Wholesale Values

3.  Retail Values

4.  Trade-in Values

5.  Standard Equipment

6.  Residual Values

7.  Color Swatch Data

8.  Trend Analysis Data

9.  Vehicle Photos

10. Finance Advance Value

11. Extra Fields (i.e. transmission, tire size, GVW, fuel type, cylinders, HP, wheel base)

12. Vehicle Specification PDF’s

Return To Table of Contents

Section I. Overview (continued)

Valuation Conditions (can only be setup by a Black Book system administrator)

Any combination of conditions can be turned on when your account is setup. The conditions have to correlate to the data types that were turned on. And it takes two minutes to change the settings later if other valuation conditions are required.

All Data Types and All Conditions / Trade-in average
Wholesale extra clean / Trade-in rough
Wholesale clean / 12 month residual
Wholesale average / 24 month residual
Wholesale rough / 30 month residual
Retail extra clean / 36 month residual
Retail clean / 42 month residual
Retail average / 48 month residual
Retail rough / 60 month residual
Trade-in clean / 72 month residual

Section II. Web Service Security

Security for the used car 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 included 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.

Return To Table of Contents

Section II. Web Service Security (continued)

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 used car 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 usedcarws.

// create web service object reference

protected usedcarws.UsedCarWS ws = new usedcarws.UsedCarWS();

// create user credentials class

protected usedcarws.UserCredentials uc = new usedcarws.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.

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/usedcarws.asmx/IPAddress

Return To Table of Contents

Section III. Web Service Function Summary

The table starting on this page 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 used car web service is UsedCarWebservices.

Function Name / Overload
(Y/N) / Overload Parameter / Function Description
getYears / N / Retrieve model year
getMakes / N / Retrieve makes by year
getModels / N / Retrieve models by year & make
getSeries / N / Retrieve series by year, make, & model
getStyles / N / Retrieve styles by year, make, model, & series
getValues / Y / History Date / Retrieve vehicle values by year, make, model, series & style
getVINValues / Y / History Date,
UVC, Maturity date,
Miles/year / Retrieve vehicle values by VIN
getMileage / Y / History Date / Retrieve mileage adjustments
getCanadianMileage / Y / History Date / Retrieve mileage adjustments
getAddDeducts / Y / History Date / Retrieve add/deduct or option adjustments
getSingleState / N / Retrieve car & truck regions for state
getAllStates / N / Retrieve car & truck regions for all states
getSingleProvince / N / Retrieve car & truck regions for province
getAllProvinces / N / Retrieve regions for all provinces
getStandardEquipment / Y / Category / Retrieve standard equipment
getColors / Y / Category / Retrieve color swatch data
getPhoto / N / Retrieve vehicle photo
getPDFSpec / N / Retrieve vehicle specification PDF
getTrendAnalysisValues / N / Retrieve trend analysis values
applyUSAdjustments / Y / History Date / Apply adjustments to U.S. vehicle
applyCanadianAdjustments / Y / History Date / Apply adjustments to Canadian vehicle
getVehicleClasses / N / Retrieve vehicle classifications
getIPAddress / N / Retrieve IP address for account setup

Note: Always check the return code and return message in the Soap Header after every function call. The return code should be zero for successful function calls. See the section, Web Service Messages for more details.

Return To Table of Contents

Section IV. Retrieving Vehicle By Drilldown

Each vehicle in the Black Book database has a vehicle description made up of five elements; year, make, model, series, and body style. One method of retrieving vehicle values and information is to traverse the vehicle description in order to find a vehicle. In other words, the user would select a year, then a make for that year, then a model for that year and make, and so on.

The used car web service uses six functions in support of the drilldown process. The function and their signatures are as follows:

1.  public DataSet getYears(string sCountryCode)

Returns:

Dataset Name / modelyears
Table Name / years
Data Element Name(s) / year

2.  public DataSet getMakes(string sCountryCode,

string sYear)

Returns:

Dataset Name / vehiclemakes
Table Name / makes
Data Element Name(s) / make

3.  public DataSet getModels(string sCountryCode,

string sYear,

string sMake)

Returns:

Dataset Name / vehiclemodels
Table Name / models
Data Element Name(s) / model

Return To Table of Contents

Section IV. Retrieving Vehicle By Drilldown (continued)

4.  public DataSet getSeries(string sCountryCode,

string sYear,

string sMake,

string sModel)

Returns:

Dataset Name / vehicleseries
Table Name / series
Data Element Name(s) / series

5.  public DataSet getStyles(string sCountryCode,

string sYear,

string sMake,

string sModel,

string sSeries)

Returns:

Dataset Name / vehiclestyles
Table Name / styles
Data Element Name(s) / style

Drilldown By Vehicle Classification

There is also a corresponding overload for each of the methods just discussed, so that a vehicle drilldown can be done by vehicle classification. In other words, if you want to simply drilldown into pickup trucks then the web service allows you to do this by specifying the vehicle classification as a part of the method call. For example, the following method signature for the getYears method would be coded as follows:

public DataSet getYears(string sCountryCode, string sVehicleClass)

The method now has a second parameter to specify the vehicle classification. Each of the drilldown methods has the same overload and add the vehicle classification as the last parameter. In order to retrieve a full list of vehicle classifications the getVehicleClasses method will need to be called.

Return To Table of Contents

Section IV. Retrieving Vehicle By Drilldown (continued)

6.  public DataSet getValues(string sCountryCode,

string sFrequencyCode,

string sYear,

string sMake,

string sModel,

string sSeries,

string sStyle,

int iMileage,

string sState,

int iExtraCleanAddDeductAdj,

int iCleanAddDeductAdj,

int iAverageAddDeductAdj,

int iRoughAddDeductAdj,

bool bFillDrilldown,

bool bReturnMileage,

bool bReturnAddDeducts,

DateTime dHistoricalDate)

Returns:

Dataset Name / vehiclevalues
Table Name / values
Data Element Name(s) / (See table next page)

(See Appendix B and C for vehicle valuation dataset schema)

Return To Table of Contents

Section IV. Retrieving Vehicle By Drilldown (continued)

The first parameter that is passed into all the drilldown functions is the country code. The valid values for the country code are as follows:

U – United States

C – Canadian

When your account is setup by a Black Book administrator your account will be set to one of these attributes. Passing in a value not associated with your account setup will result in an error being returned in the soap header.

The example below illustrates how the country code is passed in when using the getYears function. The code was written in C#.

DataSet ds = new DataSet();

ds = ws.getYears("U”);

The sample function call passed in a “U” for United States, so that all the model years will be returned in descending order. A more complex example involves the getValues function call, because there are 16 required parameters and 1 optional parameter.

DataSet ds = new DataSet();

ds = ws.getValues("U", "D", “2004”, “Ford”, “Expedition”, “XLT”, “4D Utility”, 0, "NT",0,0,0,0, false, true, true);

The parameters for the function call are as follows:

Country Code / U = United States / Extra Clean Add/Deduct / 0
Frequency Code / D = Daily Data / Clean Add/Deduct / 0
Year / 2004 / Average Add/Deduct / 0
Make / Ford / Rough Add/Deduct / 0
Model / Expedition / DrillDown Population / false
Series / XLT / Return Mileage Adj. / true
Style / 4D Utility / Return Add/Deduct Adj. / true
Mileage / 0 / Historical Date / Null (optional)
State / NT or National

Return To Table of Contents

Section IV. Retrieving Vehicle By Drilldown (continued)

It is important to discuss the last four parameters in the getValues function call, because they will appear on all function calls that return values. Specifically, the bFillDrilldown, bReturnMileage, bReturnAddDeducts, and dHistoricalDate parameters.

bFillDrilldown (required)

This parameter 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 five other data tables would be returned with the year, make, model, series, and body styles. If six data tables were created and loaded from the dataset the code would look like the following example.

DataTable dtValues = ds.Tables[“values”];

DataTable dtYears = ds.Tables[“years”];

DataTable dtMakes = ds.Tables[“makes”];

DataTable dtModels = ds.Tables[“models”];

DataTable dtSeries = ds.Tables[“series”];