# True North Tires customer catalog API

Guide: https://finder.truenorthtires.ca/catalog-api.md
OpenAPI: https://finder.truenorthtires.ca/catalog-openapi.json
Finder: https://finder.truenorthtires.ca/finder

## Give your AI this prompt

Read https://finder.truenorthtires.ca/catalog-api.md and use its read-only API to find
205/55R16 tires for Newfoundland and Labrador (NL). Show up to five options,
CAD price each and for four, product-page links, and inventoryAsOf. Explain
stock and price caveats. Do not infer vehicle compatibility or place an order.

Your assistant needs browsing and/or an HTTP API tool to fetch documentation
and JSON. A model without these tools cannot perform a current search. A URL
or discovery metadata does not guarantee that any assistant will call the API.
These documents and metadata are public, not an AI-only access boundary.

## Supported call

GET https://finder.truenorthtires.ca/api/muse/catalog-search

Anonymous JSON response; no credentials needed. This guide advertises only
customer product lookup. It cannot reserve stock, purchase, create checkout,
or contact customers. Use the returned productUrl to visit the store.

Query parameters (URL-encode values; send each parameter only once):

| Parameter | Contract |
| --- | --- |
| province | Required. NL, NS, NB, PE, QC, ON, MB, SK, AB, BC. Trimmed and uppercased; territories unsupported. |
| q | Required unless all vehicle fields are supplied. Trimmed, 2–100 characters; no %, underscore, or backslash wildcards. |
| category | all (default), tire, or wheel; case-sensitive. Vehicle searches reject wheel and return tire. |
| limit | Integer 1–20; default 10. Caps returned products, not a page size. |
| make | Vehicle make identifier as selected in Finder; trimmed, at most 80 characters. |
| model | Vehicle model identifier as selected in Finder; trimmed, at most 100 characters. |
| year | Vehicle year: exactly four digits. |
| trim | Vehicle trim identifier as selected in Finder; trimmed, at most 100 characters. |

If any vehicle field is provided, all four are required and nonempty. Vehicle
fields take precedence over q (q is ignored in vehicle mode). Use the exact
identifiers selected in Finder, not an engine label or guessed display name.

## Copyable searches

- Tire size: https://finder.truenorthtires.ca/api/muse/catalog-search?q=205%2F55R16&province=NL&category=tire&limit=5
- Wheel specification: https://finder.truenorthtires.ca/api/muse/catalog-search?q=17x7.5+5x114.3&province=ON&category=wheel&limit=5
- Keyword: https://finder.truenorthtires.ca/api/muse/catalog-search?q=Michelin&province=NL&category=tire&limit=5
- Cached vehicle example: https://finder.truenorthtires.ca/api/muse/catalog-search?make=Honda&model=Civic&year=2020&trim=EX&province=ON&category=tire&limit=5

For example:

```sh
curl --get 'https://finder.truenorthtires.ca/api/muse/catalog-search' --data-urlencode 'q=205/55R16' --data-urlencode 'province=NL' --data-urlencode 'category=tire' --data-urlencode 'limit=5'
```

These are executable requests, not promises of matching stock. Empty products
with count 0 is a successful search. Tire sizes must start q; LT/P/ST prefixes
are recognized. Wheels must start q with diameter x width and optionally bolt
pattern (for example 17x7.5 5x114.3). Trailing words filter the matching products
as one case-insensitive substring, not independent search terms. Other q values
use substring matching. There is no pagination or exhaustive keyword search:
the keyword database scan is capped at 200 candidates before customer filtering.
Keyword results have no promised sort order.

Vehicle search uses cached Finder tire sizes together with each option's minimum
load index and speed rating, and returns only selectable verified matches.
Load the vehicle's
fitment in Finder first; an uncached selection returns 404, not guessed matches.
The Honda example is illustrative and needs that exact cached selection.
Vehicle results combine distinct products for all recorded front/rear sizes and
options, ordered by price before the result cap. This is a union, not a matched
front/rear package. No axle, option, load/speed rating, or wheel compatibility
certification is provided. Text mentioning a vehicle is NOT a verified fitment.

## Response

Every 200 response is an object with exactly these fields:

| Field | Meaning |
| --- | --- |
| query | Trimmed q, or year make model trim in vehicle mode. |
| province | Normalized selected province. |
| category | Requested category; tire in vehicle mode. |
| searchMode | exact-tire-size, wheel-specification, text, or vehicle-fitment. |
| inventoryAsOf | Recorded last completed catalog sync time string, or null when unknown. Not a live stock check. |
| inventoryNote | Stock and pricing warning; preserve it when explaining results. |
| products | Array capped by limit. Only active, positively priced, destination-eligible customer products with known stock, or approved preorders. |
| count | Number of products returned; not the total matches. |
| resultsMayBeIncomplete | true when the text candidate scan hits 200; false does NOT prove exhaustive results because limit still truncates and destination filtering can remove candidates. |

Each product has exactly these fields:

| Field | Meaning |
| --- | --- |
| handle | Store product handle. |
| title | Customer product title. |
| brand | Customer brand. |
| category | tire or wheel. |
| productUrl | Absolute https://truenorthtires.ca/products/ link. |
| priceEach | CAD price per item, rounded to cents. |
| finderCompatibility | Optional Finder classification: verified, unknown, or blocked. Vehicle results are always verified; size-only or keyword lookup is not vehicle-fitment certification. |
| selectable | Optional boolean, present alongside finderCompatibility. False means review-only: do not recommend it as verified fitment or treat it as a selectable tire. |
| priceForFourBeforeTaxesShippingAndPromotions | CAD arithmetic price for four; excludes tire levies too. Not a checkout quote. |
| currency | CAD. |
| availableQuantityForProvince | Known destination-eligible quantity from the catalog mirror; not total national stock or reserved stock. |
| singleSourceSetOfFourAvailable | Whether one eligible source has at least four; false can still mean a combined quantity of four or more. |
| preorder | Approved preorder; may have zero on-hand stock. Do not represent it as physically in stock. |

Stock can change after the last completed product sync. A null inventoryAsOf
means freshness is unknown. Confirm availability before promising or accepting
an order. Prices exclude taxes, shipping, tire levies and promotions. Eligible
inventory does not guarantee delivery to every address, checkout acceptance,
shipping prices, free shipping, or delivery timing. No private stock-source
breakdown is returned.

## Errors, throttling and caching

Errors are JSON objects with an error string:

- 400: invalid q, province, category, limit, or missing/invalid vehicle fields.
- 404: no verified cached vehicle fitment, or cached fitment has no valid tire sizes.
- 429: Search limit reached. Retry in a minute. Retry-After: 60.
- 500: Catalog search failed. Retry later; do not substitute invented products.

Search allows 30 requests per client IP in a rolling 60-second window in each
server process. Invalid requests also count; shared IPs share the allowance.
HTTP caches may reuse successful searches for 30 seconds (Cache-Control:
private, max-age=30); this does not refresh the underlying inventory.
Never treat a failed request as an empty successful result.