Bid Estimator API

1. Get an API key

Keys are issued by the Autocheck team — contact us with your company name and intended use. A key is shown to you once; store it securely and only use it server-side (never in a browser or mobile app). If a key leaks, ask us to revoke it and issue a new one.

2. Authenticate

Send the key as a bearer token on every request. Base URL: https://autocheck.jp/api/v1

Authorization: Bearer <your-api-key>
Accept: application/json

A missing, unknown or revoked key returns 401.

3. Integration flow

1. The user enters a model / chassis code (e.g. AGH30W).
2. Call options to get the trims, years and colours that actually exist for that code, and fill your dropdowns from it.
3. The user picks a year (required), mileage ceiling (required), and optionally trim, colour and body score(s).
4. Call estimate and show the average price and the comparable results.

4. GET /bid-estimator/options

Input options for a model code.

curl -H "Authorization: Bearer $AUTOCHECK_API_KEY" \
  "https://autocheck.jp/api/v1/bid-estimator/options?code=AGH30W"

Example response (illustrative values):

{
  "data": {
    "code": "AGH30W",
    "exists": true,
    "variants": ["2.5S", "2.5S A PACKAGE", "2.5S C PACKAGE", "2.5Z G EDITION"],
    "years": [2023, 2022, 2021],
    "colors": ["BLACK", "PEARL", "WHITE"],
    "scores": ["S", "6", "5", "4.5", "4", "3.5", "3", "R"],
    "max_mileage_km": 150000
  }
}

• exists is false when there are no auction results for the code at all.
• variants only lists trims with at least one recorded sale.
• years are newest first.

5. GET /bid-estimator/estimate

Comparable auction results and their average. Every filter you send is exact.

curl -G -H "Authorization: Bearer $AUTOCHECK_API_KEY" \
  "https://autocheck.jp/api/v1/bid-estimator/estimate" \
  --data-urlencode "code=AGH30W" \
  --data-urlencode "variant=2.5S C PACKAGE" \
  --data-urlencode "year=2023" \
  --data-urlencode "max_mileage=150000" \
  --data-urlencode "scores[]=4.5" \
  --data-urlencode "scores[]=4"

Example response (illustrative values):

{
  "data": {
    "query": {
      "code": "AGH30W", "variant": "2.5S C PACKAGE", "year": 2023,
      "max_mileage": 150000, "color": null, "scores": ["4.5", "4"]
    },
    "count": 2,
    "average_price_yen": 4475000,
    "results": [
      {
        "odo": 12, "final_price": 4550,
        "scores_body": 4.5, "scores_body_label": "4.5", "scores_interior": "A",
        "model": "ALPHARD 2.5S C PACKAGE", "type": "AGH30W", "year": 2023,
        "color": "PEARL", "bid_site": "USS Tokyo", "capture_date": "2026-10-28"
      },
      {
        "odo": 25, "final_price": 4400,
        "scores_body": 4.0, "scores_body_label": "4", "scores_interior": "B",
        "model": "ALPHARD 2.5S C PACKAGE", "type": "AGH30W", "year": 2023,
        "color": "BLACK", "bid_site": "TAA Kinki", "capture_date": "2026-10-21"
      }
    ]
  }
}

• Up to 15 results, most recently captured first.
• If fewer than 2 results match, count is 0, results is empty and average_price_yen is null — loosen a filter and retry.

6. Units

7. Errors and rate limits

HTTP/1.1 422 Unprocessable Content
{
  "message": "The year field is required.",
  "errors": { "year": ["The year field is required."] }
}

Results change as new auctions are captured, so cache responses for minutes, not days.