Searching the Webservice

From Car and Driving
(Difference between revisions)
Jump to: navigation, search
(One intermediate revision by one user not shown)

Latest revision as of 11:27, 24 June 2020

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.

[edit] 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.

[edit] 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.

[edit] 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.

Personal tools