Searching the Webservice

From Car and Driving
Jump to: navigation, search

The webservice is found at: (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.

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.


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.

Personal tools