API Reference: SureCritic Public API (v0.7)

Getting started

Overview

The SureCritic API is entirely HTTP-based and follows the design principles of REST. Methods that retrieve data use GET; methods that submit, update, or destroy data use POST, PUT, and DELETE respectively. The public resources documented here are read-only and use GET.

Reviewshttps://www.surecritic.com/api/pub

Vehiclehttps://vehicle-api.surecritic.com/api/vehicle

Versioning. This reference documents v0.7. Recent additions include Vehicle Review summary methods, NPS® in business results, and a syndication URL for the vehicle API.

Getting started

Authentication

Every request requires an api_key query parameter that identifies the API user making the request. All traffic should be sent over HTTPS.

Example request

GET https://www.surecritic.com/api/pub/businesses.json?api_key=YOUR_API_KEY

Keys are issued by an administrator. API keys are not self-service. To request access, contact your SureCritic administrator or account team. Keep your key secret. Never embed it in client-side code or public repositories.

IP allowlisting. API access is locked to pre-registered IP ranges. Requests from addresses outside your allowlist are rejected with a 403. Send the egress IP ranges that will call the API to your administrator when requesting a key.

Getting started

Formats & responses

Response format is driven by the file extension in the request path. Append .json or .xml to any resource. When using XML, no DTD is provided. Field names are self-explanatory.

Some business actions also support JSONP: use the .jsonp extension and add a callback parameter. The response is wrapped as a JavaScript call to your callback function.

JSONP

GET https://www.surecritic.com/api/pub/businesses/{slug}.jsonp?callback=myCallback

Getting started

Status codes

The response status indicates the result of the call. Error details, when present, are included in the response body.

200	Success.
201	Created.
202	Request received and queued for asynchronous processing.
204	Success, but there is no response body.
400	Bad request. Errors are listed in the response body.
403	Not authorized. Your `api_key` was missing or invalid, or the request came from a non-allowlisted IP.
404	Not found. The business or other entity could not be found.
422	Unprocessable entity. Validation errors are included in the response body.
500	Server error.

Resource

Businesses

The primary interface for querying business summary information. Businesses are identified by their id or slug. The slug is the trailing segment of a SureCritic reviews URL, e.g. car-pros-burien-nissan in surecritic.com/reviews/car-pros-burien-nissan.

GET

Extract slug

Extracts a business's slug from its full reviews-page (BRP) URL.

GEThttps://www.surecritic.com/api/pub/businesses/extract_slug.{format}

Formats: XML, JSON, JSONP

Parameters

Name	Type	Description
api_keyRequired	string	Identifies the API user making the request.
brp_urlRequired	string	The full SureCritic URL to extract the slug from.

Sample response

<response>
  <brp_url>https://www.surecritic.com/reviews/corys-magic-carpets</brp_url>
  <slug>corys-magic-carpets</slug>
</response>

GET

List businesses

Returns a paginated list of businesses by keyword and/or location. Up to 30 businesses per request, sorted by relevance or distance depending on the parameters supplied.

GEThttps://www.surecritic.com/api/pub/businesses.{format}

Formats: XML, JSON, JSONP

Parameters

Name	Type	Description
api_keyRequired	string	Identifies the API user making the request.
termOptional	string	A string used for text-based search.
latOptional	decimal	Latitude in decimal degrees. Paired with `lng` to center the search.
lngOptional	decimal	Longitude in decimal degrees. Paired with `lat` to center the search.
postcodeOptional	string	Usually a 5-digit US ZIP code, used to center the search.
radiusOptional	integer	Search radius in miles around the coordinates or postcode. Defaults to 25; clamped between 5 and 250.
pageOptional	integer	Page number for the request. Defaults to 1.

Sample response

<businesses>
  <current_page type="integer">1</current_page>
  <per_page type="integer">30</per_page>
  <total_entries type="integer">2</total_entries>
  <total_pages type="integer">1</total_pages>
  <businesses type="array">
    <business>
      <id type="integer">1</id>
      <name>Cory's Magic Carpets</name>
      <slug>corys-magic-carpets</slug>
      <brp_url>http://www.surecritic.com/reviews/corys-magic-carpets</brp_url>
      <review_count type="integer">6</review_count>
      <rating_avg type="decimal">3.66667</rating_avg>
      <recommend_pct type="decimal">100.0</recommend_pct>
      <rescore_count type="integer">6</rescore_count>
    </business>
  </businesses>
</businesses>

GET

Show business

Returns a single business's full details, including address, contact info, departments, NPS®, and ReScore® counts.

GEThttps://www.surecritic.com/api/pub/businesses/{id}.{format}

GEThttps://www.surecritic.com/api/pub/businesses/{slug}.{format}

Formats: XML, JSON, JSONP

Parameters

Name	Type	Description
api_keyRequired	string	Identifies the API user making the request.

Sample response

<business>
  <id type="integer">1</id>
  <name>Cory's Magic Carpets</name>
  <slug>corys-magic-carpets</slug>
  <brp_url>http://www.surecritic.com/reviews/corys-magic-carpets</brp_url>
  <review_count type="integer">6</review_count>
  <rating_avg type="decimal">3.66667</rating_avg>
  <nps_score type="integer">82</nps_score>
  <recommend_pct type="decimal">100.0</recommend_pct>
  <rescore_count type="integer">6</rescore_count>
  <address>
    <line_1>123 Main Street</line_1>
    <municipality>Seattle</municipality>
    <postcode>98103</postcode>
    <region>WA</region>
    <latitude type="decimal">47.657845</latitude>
    <longitude type="decimal">-122.351841</longitude>
  </address>
  <phone>(206) 555-1212</phone>
  <website>http://www.corysmagiccarpets.com</website>
  <email_address>cory@example.com</email_address>
  <departments>
    <department>
      <department_id type="integer">1</department_id>
      <name>Sales</name>
      <review_count type="integer">6</review_count>
      <rating_avg type="decimal">3.66667</rating_avg>
      <recommend_pct type="decimal">100.0</recommend_pct>
      <rescore_count type="integer">1</rescore_count>
    </department>
  </departments>
</business>

GET

Business reviews

Returns the most recent reviews for a business, including ratings, recommendation flags, verification status, vehicle details, and any business responses.

GEThttps://www.surecritic.com/api/pub/businesses/{id}/reviews.{format}

GEThttps://www.surecritic.com/api/pub/businesses/{slug}/reviews.{format}

Formats: XML, JSON, JSONP

Parameters

Name	Type	Description
api_keyRequired	string	Identifies the API user making the request.
countOptional	integer	Number of reviews to return. Defaults to 10; never more than 50.

Sample response

<reviews>
  <review>
    <id type="integer">5471</id>
    <review_url>http://www.surecritic.com/reviews/hyundai-of-arlington?review_id=5471</review_url>
    <department_id type="integer">1</department_id>
    <rating type="integer">5</rating>
    <recommends type="boolean">true</recommends>
    <has_rescore type="boolean">false</has_rescore>
    <display_name>Bob S.</display_name>
    <location>Kirkland, WA</location>
    <title>Great experience buying a new car</title>
    <comments>Lorem ipsum dolor</comments>
    <verified type="boolean">true</verified>
    <created_date>2013-08-16</created_date>
    <service_date>2013-08-16</service_date>
    <year>2013</year>
    <make>Nissan</make>
    <model>Altima</model>
    <rescore_review></rescore_review>
    <responses>
      <response>
        <name>A. Responder</name>
        <created_date>2013-08-19</created_date>
        <comments>Lorem ipsum dolor</comments>
      </response>
    </responses>
  </review>
</reviews>

Resource

Vehicle Reviews

Query aggregated vehicle review scores and individual vehicle reviews by make, model, and year. These methods are served from the vehicle API host.

Business attribution. Supplying a business key sets the review_url in the response to that business. Use business_slug (unique to SureCritic) or business_external_id. External IDs are not globally unique (they map to a dealer code for a specific partner), so requests using one must authenticate with that partner's API key.

GET

Summary scores

Returns aggregate review scores for a vehicle, scoped by make, make + model, or make + model + year.

GEThttps://vehicle-api.surecritic.com/api/vehicle/{make}.{format}

GEThttps://vehicle-api.surecritic.com/api/vehicle/{make}/{model}.{format}

GEThttps://vehicle-api.surecritic.com/api/vehicle/{make}/{model}/{year}.{format}

Formats: XML, JSON

Parameters

Name	Type	Description
api_keyRequired	string	Identifies the API user making the request.
business_slugOptional	string	Attribute results to a business by its SureCritic slug.
business_external_idOptional	string	Attribute results by a partner dealer code. Requires a partner-specific API key.

Sample response

<vehicles>
  <year>2019</year>
  <make>hyundai</make>
  <model>sonata</model>
  <reviews_url>https://www.surecritic.com/vehicles/iframe/reviews/hyundai/sonata/2019?business_slug=hyundai-of-newport</reviews_url>
  <reviews type="integer">479</reviews>
  <overall-rating type="float">4.728601252609604</overall-rating>
  <recommend-vehicle type="float">9.382045929018789</recommend-vehicle>
  <comfort type="float">9.375782881002088</comfort>
  <build-quality type="float">9.313152400835072</build-quality>
  <performance type="float">9.160751565762004</performance>
  <fun-to-drive type="float">9.152400835073069</fun-to-drive>
  <features type="float">9.250521920668058</features>
  <value-for-the-money type="float">9.33820459290188</value-for-the-money>
  <reliability type="float">9.450939457202505</reliability>
  <overall-styling type="float">9.36116910229645</overall-styling>
  <interior-design type="float">9.30062630480167</interior-design>
  <exterior-design type="float">9.296450939457202</exterior-design>
</vehicles>

GET

Review details

Returns individual, paginated vehicle reviews with full per-category ratings, pros, and cons.

GEThttps://vehicle-api.surecritic.com/api/vehicle/{make}/{model}/{year}/reviews.{format}

Formats: XML, JSON

Parameters

Name	Type	Description
api_keyRequired	string	Identifies the API user making the request.
afterOptional	date	Return results completed after this date (`YYYY-MM-DD`).

Sample response

<vehicle-reviews>
  <current_page type="integer">1</current_page>
  <per_page type="integer">100</per_page>
  <total_entries type="integer">3</total_entries>
  <total_pages type="integer">1</total_pages>
  <year>2017</year>
  <make>bmw</make>
  <model>x5</model>
  <vehicle-reviews type="array">
    <vehicle-review>
      <name>GEORGE D.</name>
      <completed_on>2017-08-09</completed_on>
      <year type="integer">2017</year>
      <make>BMW</make>
      <model>X5</model>
      <overall-rating type="integer">5</overall-rating>
      <recommend-vehicle type="integer">8</recommend-vehicle>
      <vehicle-review-title>Great quality and styling</vehicle-review-title>
      <vehicle-review-summary>Good quality vehicle with updated features and the latest technology. Great styling and a great ride.</vehicle-review-summary>
      <comfort type="integer">9</comfort>
      <build-quality type="integer">9</build-quality>
      <performance type="integer">7</performance>
      <reliability type="integer">10</reliability>
      <pros>Luxurious interior with a comfortable ride.</pros>
      <cons>Base engine lacks power.</cons>
    </vehicle-review>
  </vehicle-reviews>
</vehicle-reviews>

Need a key, additional scopes, or the partner provisioning & stats APIs? Talk to our team.

SureCritic API reference.

Overview

Authentication

Formats & responses

Status codes

Businesses

Extract slug

List businesses

Show business

Business reviews

Vehicle Reviews

Summary scores

Review details