Tire Size & Wheel Fitment API Help Center

Authentication & API Keys

Log in to account-tire.vdim.app/account and click the API Key tab
Your active key is displayed there — copy it to use in your requests
You can regenerate it at any time — regenerating immediately invalidates the old key

Pass it as a request header named x-api-key — do not put it in the URL as a query parameter

# cURL
curl -H "x-api-key: YOUR_API_KEY" "https://tire.vdim.app/api/v1/..."

# JavaScript (fetch)
fetch("https://tire.vdim.app/api/v1/...", {
  headers: { "x-api-key": "YOUR_API_KEY" }
});

# Python (requests)
import requests
r = requests.get("https://tire.vdim.app/api/v1/...",
  headers={"x-api-key": "YOUR_API_KEY"})

Check that the header name is exactly x-api-key — not X-API-Key or apikey
Make sure you haven't exceeded your daily request limit — check your dashboard usage
If your subscription expired, renew it from the Plans section
If you regenerated your key recently, update it in your code — the old key is permanently invalidated
If none of the above apply, contact support

Making Requests

Use the /tire_dimensions endpoint with year, make, model, and trim:

GET /api/v1/tire_dimensions?year=2022&make=Toyota&model=Camry&trim=LE

All four parameters are required — omitting any of them returns 400 Bad Request listing what's missing
Use /search_allyear and /search_allmake first to get valid values for dropdowns, then /by_vehicle/model and /by_vehicle/trim to narrow down
Optionally add tiresize to filter the returned dimensions to one specific size

Search by aspect ratio — returns matching tire sizes for a given width:

GET /api/v1/by_size/aspectratio?width=225

Search by diameter — narrows results by width and aspect ratio:

GET /api/v1/by_size/diameter?width=225&aspectratio=45

Send a 17-character VIN and get the decoded vehicle plus its factory tire sizes:

GET /api/v1/by_vin/1HGCM82633A004352

VIN lookups use a monthly quota separate from your daily limit: Free 10, Starter 500, Pro 5,000, Business 20,000 (Free plans also get a one-time 50-lookup welcome bonus)
Track remaining lookups via the X-VIN-Quota-Remaining response header or GET /api/v1/usage; the quota resets on the first of each month (America/Toronto)

Use /reverse_lookup with a full size string, or with the individual dimensions:

GET /api/v1/reverse_lookup?tiresize=225/60R16
GET /api/v1/reverse_lookup?width=225&aspectratio=60&diameter=16

Returns a vehicles array of year / make / model / trim combinations that use that size
Reverse lookups use a monthly quota separate from your daily limit: Free 10, Starter 5,000, Pro 20,000, Business 60,000 (Free plans also get a one-time 10-lookup trial bonus)
Track it via the X-RevLookup-Quota-Remaining header or GET /api/v1/usage; it resets on the first of each month (America/Toronto)

Business plans can pull every distinct tire size in the database in a single call — no parameters needed:

GET /api/v1/search_allsizes

Returns size strings only (no vehicle or fitment linkage) — built for seeding a size picker or your own sizing engine
Business plan only — other plans receive 403 Business subscription required
Metered at 500 calls per month, reported via the X-AllSizes-Quota-* headers
Cached for an hour (Cache-Control: public, max-age=3600), so one refresh per day is normally plenty

On another plan? Build a size list from /search_allwidth plus /by_size/aspectratio and /by_size/diameter.

All makes: GET /api/v1/search_allmake
All years: GET /api/v1/search_allyear
All widths: GET /api/v1/search_allwidth
Year range for a make: GET /api/v1/year_range?make=Toyota

These endpoints are highly cacheable — cache for at least 24 hours to reduce your daily usage

Each plan has a daily request limit that resets at midnight Eastern Time (America/Toronto)
Free: 300 requests/day (up to 100/hour)
Starter: 5,000 requests/day
Pro: 50,000 requests/day
Business: 80,000 requests/day (custom limits available)
When you hit the limit you receive a 429 Too Many Requests response — monitor usage from your dashboard

Monthly endpoint quotas. Three endpoints carry a monthly quota in addition to your daily limit. These reset on the first of each month (America/Toronto):

Endpoint	Free	Starter	Pro	Business
`/by_vin/{vin}`	10 (+50 one-time)	500	5,000	20,000
`/reverse_lookup`	10 (+10 one-time)	5,000	20,000	60,000
`/search_allsizes`	—	—	—	500

Everything else — including /by_vehicle, the vehicle → tire size direction most applications use — runs on the daily limit only
Read Fair Use & Data Protection for the full picture, or call GET /api/v1/usage to see your current numbers

Understanding Responses

{
  "success": true,
  "dimensions": [
    {
      "width": "235",
      "aspectratio": "45",
      "diameter": "18",
      "tiresize": "235/45R18"
    }
  ],
  "action": "getTireDimensions",
  "metadata": {
    "vehicle": {
      "year": "2022",
      "make": "Toyota",
      "model": "Camry",
      "trim": "LE"
    },
    "requestedTireSize": "all",
    "matchedCount": 1,
    "totalAvailable": 1,
    "extractionMethod": "direct_database_fields"
  },
  "timestamp": "2026-08-02T10:30:00.000Z"
}

dimensions is always an array — a vehicle configuration can have more than one approved size
Pass tiresize in the request to narrow it to a single size; metadata.requestedTireSize echoes what you asked for and matchedCount / totalAvailable tell you how much was filtered out
Individual fields are returned as strings and can be null where the source record is incomplete

Note: The API returns OEM tire sizes. Load index and speed rating are not part of the dataset.

Daily limit — X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset (Unix timestamp of the next midnight America/Toronto), and X-Subscription-Type
Free plan only — X-RateLimit-Hourly-Limit and X-RateLimit-Hourly-Remaining
Monthly quotas — X-VIN-Quota-Limit / -Remaining / -Reset, and the same three for X-RevLookup-Quota-* and X-AllSizes-Quota-*
One-time bonuses — X-VIN-Bonus-Remaining and X-RevLookup-Bonus-Remaining appear only while a bonus is still available
Diagnostics — X-Response-Time reports server-side processing time in milliseconds

Tip: Quota headers appear on the endpoint that consumes them. For a single view of everything, call GET /api/v1/usage.

Different trim levels often come with different wheel and tire sizes
Example: a base LE trim may use 17" wheels while the XSE uses 18"
Always filter by trim for exact fitment, or display all trims and let the user select theirs

Error Troubleshooting

Code	Meaning	Fix
401	Unauthorized	Missing or invalid `x-api-key` header
403	Forbidden	The endpoint needs a higher plan (e.g. `/search_allsizes` is Business-only), your subscription expired, or access was restricted under the fair-use terms
429	Daily / hourly limit	`"Daily API request limit exceeded"` or `"Hourly API request limit exceeded"` — wait for the midnight (or top-of-hour) Eastern Time reset, or upgrade
429	Monthly quota	`"Monthly VIN quota exceeded"`, `"Monthly reverse-lookup quota exceeded"`, or `"Monthly size-catalog quota exceeded"` — resets on the first of next month (America/Toronto)
429	Throttled	`"Access temporarily throttled"` — bulk-access patterns detected. Stop the bulk job; access restores once the key is quiet. Honour `Retry-After` and see the guide below
404	Not Found	No data found — check spelling of make/model/year
400	Bad Request	Missing required parameter — check the API docs
500	Server Error	Our side — check API Status and retry

Header name must be exactly x-api-key — not X-API-Key or apikey
Check for leading or trailing spaces in the key value
Confirm your subscription is active in your dashboard
If you recently regenerated your key, make sure you're using the new one

Use /search_allmake to get the exact make string — spelling matters (e.g. Land Rover not Land-Rover)
Use /year_range?make=Toyota to confirm the year is within our dataset
Try without the trim parameter to get all trims for that model first

Two endpoints are gated to the Business plan: /search_allsizes and /premium/advanced-search
The response includes your currentPlan so you can confirm which plan the key is on
On another plan, build a size list from /search_allwidth plus /by_size/aspectratio and /by_size/diameter instead
Getting 403 Subscription expired instead? Renew from your dashboard — the response includes the expiredOn date

These two responses mean unusual bulk-access patterns were detected on your API key, and access was restricted under Terms of Use §7.1
429 Access temporarily throttled clears by itself — but only once the key has actually gone quiet. Stop the bulk job. Waiting is not enough on its own: a script that keeps retrying at speed will stay throttled for as long as it runs, however many hours or days that is
Honour the Retry-After header — it is the earliest your key can be reconsidered, not a guarantee. A client that backs off to one call an hour counts as quiet and will clear
Each repeat throttle needs a longer quiet period than the last, and after several the key stops clearing automatically and needs a support review
If the 429 arrives with no Retry-After header, that review point has been reached — contact support
403 Access suspended is reviewed by a person. Contact support to have it looked at; tell us what your integration does and we'll get you unblocked if it's legitimate
Common innocent causes: a backfill or migration script iterating over every vehicle or size, a retry loop with no backoff, or a cron job re-fetching data you could cache
Practical fixes: cache the reference endpoints (/search_allyear, /search_allmake, /search_allwidth) for at least a day, request data on user action rather than pre-fetching it, and add exponential backoff

Changing plans is not the fix. These terms apply identically on every plan, including Business. If your workload genuinely requires bulk or full-catalog data, ask us about a commercial data license — that's the supported path.

Read the error field — a 429 can come from your daily limit, your hourly limit (Free plan), a monthly endpoint quota, or a throttle
Monthly quota: /by_vin, /reverse_lookup, and /search_allsizes each have their own monthly allowance that is separate from the daily count — check GET /api/v1/usage
Free plan hourly cap: 100 requests per hour, resetting at the top of each hour (America/Toronto)
Burst protection: sending more than about a request per second from one key trips a short cooldown — spread requests out and reuse cached reference data

Account & Billing

Log in to account-tire.vdim.app/account and go to the Usage tab
You'll see your daily request count and remaining quota
Or call GET /api/v1/usage with your API key to get usage data programmatically
The /usage response also includes three monthly quota blocks — vinQuota, reverseLookupQuota, and allSizesQuota — each with monthlyLimit, monthlyUsed, monthlyRemaining, and resetTime
allSizesQuota.monthlyLimit is null on plans without size-catalog access, and bonusRemaining appears while a one-time bonus is still unused

Go to your dashboard and click Plans
Select the new plan
Confirm — upgrades take effect immediately, downgrades apply at the next billing cycle

Go to your dashboard, click Plans, then Cancel Subscription
Access continues until the end of the billing period, then reverts to the Free tier (300 requests/day)
Having trouble? Contact us and we'll help

Go to your dashboard, click the API Key tab, then Regenerate Key
Your old key is invalidated immediately — update all your applications first

How can we help?

Getting Started

Authentication

Making Requests

Still need help?

How can we help?

Getting Started

Authentication

Making Requests

Still need help?

💬 Chat with us!