# carstandings.com

> Car data per market and model year. The launched markets publish no
> composite score.

Each market-year's score_scale says which product it is.
- product = "figures": NO overall score, no rank, no factor score. Each car
  carries published_figures (a raw measured value only where a publisher
  measured that quantity for that car), figure_provenance (who measured it and
  on what basis) and figures_withheld (why each absent figure is absent). Lists
  are ordered by ONE measured figure at a time and make exactly one claim;
  sort=catalogue makes none. score_scale.no_composite says why there is no
  overall score.
- otherwise: a composite over the factors score_scale.factors_used names.

Markets: us, ca. No other market is served; any endpoint given
another country answers 404 with market_not_available=true.

API base URL: https://api.carstandings.com
All endpoints under /api/v1/. https://carstandings.com is the website; it does
not answer the API.

AUTHENTICATION IS REQUIRED on /api/v1/market, /car, /countries, /factors, /stats
and /images: sign in with a session, or send an X-API-Key. A request with neither
answers 401 (code authentication_required) and carries no data; an unknown or
revoked key answers 401 (invalid_api_key, api_key_revoked). Being a search or
AI-answer crawler changes nothing: there is no crawler exception. Create a free
account at https://carstandings.com/account/?auth=signup.

A "figures" market's PUBLIC SET is fuel_economy, fuel_economy_mpge, co2, co2_charge_weighted, crash_rating, recalls. What each plan reads:
- free account: the public set on ANY car. GET /api/v1/car carries the public
  set with values and every other figure's name, unit and publisher with the
  value withheld (reason "requires_account"), for up to 25
  DIFFERENT cars per UTC day per account; reading a car again the same day costs
  nothing. The next different car answers 429 (code daily_car_limit, with
  reads_left_today 0 and quota.resets_at) and the count restarts at 00:00 UTC.
  GET /api/v1/market lists every car with the public set on every row.
- data or api: every car in full with no daily limit, and the public set on every row of the list.
A paid plan buys GET /api/v1/bulk, the whole market-year as one attributed file:
- data: the bulk record by signed-in session, 25 market-year downloads a day.
  No API key.
- api: up to 10 API keys (X-API-Key: cs_live_<32 chars>), each with a name and an
  expiry date, managed in the account. 1,000 requests a day for the whole
  account, shared by all its keys, the bulk record uncapped, and /api/v1/compare,
  /api/v1/manufacturer, /api/v1/vin and /api/v1/ask.
/api/v1/factors, /api/v1/countries and /api/v1/stats need a free account or a key.
Spec: https://api.carstandings.com/api/v1/schema
Website: https://carstandings.com

Endpoints:
- GET /api/v1/market?country=&year=&sort=&per_page=&page=  (the market-year's cars, in catalogue order or ordered by one measured figure)
- GET /api/v1/countries                              (the launched markets, and which plans are on sale)
- GET /api/v1/factors?country=&year=                 (the market-year's published figures or factors, and its score_scale)
- GET /api/v1/stats?country=&year=                   (aggregate stats)
- GET /api/v1/car?make=&model=&year=&country=        (single car; full on a paid plan; the public set on the free plan: the Top 10 cars always, any other 25 different cars a day)
- GET /api/v1/bulk?country=&year=&format=            (the bulk record: jsonl, csv, xml, xlsx or manifest; paid plans)
- GET /api/v1/compare?make=&make=&country=&year=     (compare manufacturers, min 2; api plan)
- GET /api/v1/manufacturer?make=&country=&year=      (manufacturer summary; api plan)
- GET /api/v1/vin?vin=&country=                      (VIN decode + match; api plan)
- POST /api/v1/ask?country=&year=                     (a question about the market-year; api plan)
- GET /api/v1/images?type=&make=&model=              (image manifests/logos)
- GET /api/v1/usage                                   (key usage; API key)
- GET /api/v1/verify                                  (verify API key)
- POST /api/v1/checkout                               (Paddle checkout; signed in)
- POST /api/v1/webhook                                (Paddle webhook)
- GET /api/v1/auth/me                                 (Clerk session)
- POST /api/v1/auth/logout                            (logout)
- GET /api/v1/schema                                  (the OpenAPI spec as JSON)
- GET /api/v1/llms.txt                                (this file)

Rate limits: api 1,000 requests a day per account, shared by all its keys; data 25 bulk downloads a day.
Above a volume a person does not reach, a free account is asked to pass a check:
after 60 whole market-years in a day. A paid plan is never asked.