From time to time, to support new features or due to changes in our underlying data schema, we need to change the IIHS API in ways that might be incompatible with current client applications. Whenever possible, we release these changes as a new version of the API while continuing to support prior versions for a reasonable time to allow for client applications to be updated.
This release adds support for vehicles to have more than one rating of each type, depending on manufacture date, feature availability, or other factors. Prior to this release, information about only the primary rating for a given model year was available via the API, with the exception of headlight ratings which have included all applicable ratings since their introduction in early 2016.
To accommodate this change, the results schema for the
single and
all methods have been
updated to add a "wrapper" element around each set of ratings of each type. For example, in API version 3, each vehicle
had a single <sideRating> element, but in version 4 each vehicle has a <sideRatings>
element which contains zero or more <rating> elements. Each of these <rating> elements
represents a side impact rating that applies to the parent vehicle and model year.
For each rating type that isn't empty, there will be one rating that should be considered the primary rating of that type
for the parent vehicle and model year. This primary rating is indicated in the API results by the isPrimary
attribute on the <rating> element. If your application needs to display a single rating of
each type for a given vehicle model year, be sure to select the rating whose isPrimary attribute has
the value true.
This release also adds a boolean isQualified attribute to all rating type elements, where in V3 this attribute only
appeared on headlightRating elements. Your application should check the value of the isQualified
attribute when displaying these ratings, and if true, should also display the contents of the adjacent qualifyingText
attribute. For more information please refer to the IIHS API display requirements.
An example mobile application which uses the IIHS ratings API and targets Android devices can be found here.
The major potentially-breaking change in this version is the inclusion of variant information in
vehicle series names and slugs. For example, the Ford Explorer had series slug explorer in version 2,
but in version 3 its series slug is explorer-4-door-suv. This change allows us to more consistently
apply ratings and other information to specific body style variants when appropriate.
This version of the API also includes TOP SAFETY PICK and TOP SAFETY PICK+ award information for past award years. Version 2 only included awards for the current award year.
Other less-disruptive changes include new parameters in photo and video URLs, and new numeric ID values for ratings, vehicle makes, and vehicle series
Despite these changes in API response content, the schema of the various responses has not changed from version 2.
Initial release of the "modern" IIHS API. (Version 1 was more of a data feed than an actual API and is no longer supported.)
Note that, due to changes in our underlying database schema we are unable to continue offering updated content to Version 2 clients beyond March 23, 2015. To receive the latest content, please update your application to use Version 3 of the IIHS API.