Searching the Webservice
The webservice is found at:
https://www.caranddriving.com/ws/A041/ws.asmx (A041 is an identifier that changes with each new release).
The webservice is documented online - open this URL in your browser, and you will get a form showing you which functions are available and their various options. There are also test forms you can use to try out the functions (but you need an account setup to use these - see below) - these work best in IE or Firefox; Chrome formats the results poorly, but can me made to display the results nicely with the right XML plugin installed.
With webservice calls, you can get at our data. The main search functions are GetReviewsFromManufacturerCategoryAndType or GetTitlesFromManufacturerCategoryAndType. These functions also support searching by cap manufacturer and model name in the search (rather than the ones Car and Driving use, which may not be exactly the same for brands like Mercedes) if the capsearch flag is set to true. the type of review.
These return a list of reviews, each of which contains editorial text, scores, photos, which cap codes the review is linked to, and a list of videos attached. Note that not all reviews have videos attached, and that many videos are shared among all the derivatives of a make/model - in general, there is a video per model range, and separate articles for the important derivatives. If a derivative is particularly important, it may have its own video as well.
Important: When using videos, please use the video_urlforiframe element and paint that in an iframe, and *not* the contents of the hdvideo element. Direct access to the mp4 files is provided for those that want to implement Google SEO on the video content only, and is not intended for direct use.
Demo Accounts
If you visit the webservice in a web browser, you will get a list of all the available functions, together with a set of test forms that you can use to try out your searches. If you want to see a demo, please use one of the following accounts as your user_id:
- demo - standard editorial feed of images and video
- industrydemo - feed of images and video licenced for commercial and sales use
- whitedemo - feed of white background images
Do not use these for live implementations.
Could Not Create SSL/TLS Secure Channel Error
Recent updates to our webservers have blocked the ability for old clients to connect to the https webserver using insecure protocols. While this isn't a problem for modern browsers which automatically use the newer protocols, some older libraries may struggle unless you explicitly tell it to use a more up to date protocol in your call. For example, in C#, put in this code before you call the webservice:
ServicePointManager.Expect100Continue = True;
ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls12 | SecurityProtocolType.Ssl3;
How to Use Our Data
Each review contains editorial text, photos, often a video, cap codes that apply to that vehicle, scores and often some data on that vehicle. Editorial text is split into a list of paragraphs, with each paragraph having a heading and body. Note that the paragraph headings are specific to the review type; i.e. a used car model guide will have different paragraphs to a new car road test. You can find the review type on the reviewtype element on the review.
Reviews will typically have one of the following 4 types; new1, new2, used or family - although there are some other categorisations as well for specialist applications; notably motorcycles and caravans. The review id will also indicate the type; the most common, new2 falling in the range 0 to 99999, new1 in 100000 to 199999, used in 200000 to 299999, family in 300000 to 399999. For some cars, we may hold the same metadata against different reviews; for example, a common car like the VW Golf may have a new2 review, a used review (which talks about what it's like to own a used car model, discussing items such as depreciation which wouldn't be relevant to a new car), and a family review where the text reflects the car from a family perspective (so may talk more about practicality and comfort, and less about performance and driving characteristics) - but they would share the same video, photos and data.
New car reviews come as new1 and new2; the vast majority of reviews are new2, and these are the ones you should meet most, especially with new cars. The new1 reviews are typically long term ownership reviews, rather than general reviews on a car, and many of our customers don't use them unless they specifically want that for a particular article.
CAP
If you want to use CAP codes, the key functions you will want to use are: GetTitlesFromCapCode, GetTitlesFromCapID, GetReviewsFromCapCode and GetReviewsFromCapID.
CAP searches may return more than one match (for example, where there is a specific article about a particular derivative model of a car, and a more general range piece). If more than one result is returned to a CAP search, the more specific article is always returned first in the review list.
Note that you should, unless you have a specific reason not to, not constrain a cap search by type. Our definition of 'type=used' is not necessarily what you would expect - it means we have a specific used car editorial for that review (which has a different set of paragraphs to what we call a 'new' car review). Instead, let the webservice choose the most appropriate review editorial for you, because it might be either 'new' or 'used' depending on the age of the car, and whether it is still in production or not.
If you want to know which capcodes link to which reviews, you can download a complete lookup table from GetCapLookupTable and call GetReviewDetailsFromID on any matching review id. Some capcodes will match to several reviews; to find the most relevant, we would recommend using the review which has the smallest number on it to get the most specific video or review. We return a count of how many capcodes match each doc in this dataset to help with this. Note than any document returned with a document id of between 1 and 199999 is a new car review, between 200000 and 299999 is a used car review, and between 300000 and 399999 is a family review. Some capcodes returned are in the 500000 and upwards range; these are vans (CAP having two ranges of id's for cars and vans that overlap - internally, and unofficially, we add 500000 to any van's cap id to tell them apart). If you search for our "unofficial" 500000 range cap id in GetReviewsFromCapID you will find the van, as you will if you use the official cap id (i.e. without 500000 added) providing you specify a type of 'van' on the call - if you don't specify the type, you will get the corresponding car instead.
Please do not take all of your cars in stock/on offer, and search for each car, one after the other cycling through your entire stock. A Cap ID lookup is a particularly expensive search, and doing it in this manner means that we can't even use caching. Use GetCapLookupTable instead (once!) if you want to build an Cap ID based index of reviews for your site - this lets you download an entire lookup table in one hit. Note that we reserve the right to revoke the 'lookup single Cap ID' privilege from user accounts that are clearly indexing everything sequentially.
Getting All Review Data At Once
To get all the review data in one hit (for example, if you want to hold the data locally and reload it every week), use GetReviewsFromManufacturerCategoryAndType, set the manufacturer to an empty string, and howmany to a large number (e.g. 999999). The query may take a minute or so to run, so it is best done by an offline data loading process, perhaps once a week to ensure the local data is kept up to date.
This is our preferred method for you to extract our data.
Example query (replace 'demo' with your user_id, and howmany=5 with howmany=999999):
Note that the amount of data this will return when howmany is set to 999999 is too much for a browser to cope with; do that from your code rather than in a web browser and it will work fine.
If you're using CAP, we have a special function that returns a lookup table of CAP id to our document id. Use GetCapLookupTable - again, it provides too much data for a browser to work with, but called from your code rather than in a web browser, it will work fine. The combination of this table with the review data should allow you to find a review for each CAP id we cover.