API Reference

The PCD Fitment REST API provides programmatic access to bolt pattern conversion, measurement, matching, offset calculations, hub ring sizing, and full fitment analysis. All endpoints return JSON and follow a consistent envelope format.

Base URL: https://pcdfitment.codecide.net

API documentation (Scalar UI): https://pcdfitment.codecide.net/api/docs
OpenAPI specification: https://pcdfitment.codecide.net/api/openapi.json

Response envelope

Every response uses the following structure:

Success

{
  "success": true,
  "data": { /* endpoint-specific payload */ },
  "metadata": {
    "processingTimeMs": 12.34,
    "timestamp": "2025-03-15T10:30:00.000Z"
  }
}

Error

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Human-readable description",
    "details": [ /* optional validation details */ ]
  }
}

Common error codes:

Code	HTTP status	Meaning
`VALIDATION_ERROR`	400	Request body failed validation.
`INTERNAL_ERROR`	500	Unexpected server error.
`NOT_FOUND`	404	The requested route does not exist.

Health check

GET /health

Returns service status and uptime. This endpoint is outside the /api prefix.

Response (200):

{
  "status": "ok",
  "timestamp": "2025-03-15T10:30:00.000Z",
  "uptime": 3600
}

Example:

curl https://pcdfitment.codecide.net/health

Convert

POST /api/convert

Convert a numeric value between metric (mm) and imperial (in).

Request body:

Field	Type	Required	Description
`value`	number	Yes	Positive number to convert.
`from`	string	Yes	Source unit: `"metric"` or `"imperial"`.

Success response (200):

{
  "success": true,
  "data": {
    "source": {
      "value": 114.3,
      "unit": "metric",
      "formatted": "114.3mm"
    },
    "converted": {
      "value": 4.5,
      "unit": "imperial",
      "formatted": "4.5in"
    },
    "factor": 0.03937007874015748
  },
  "metadata": { ... }
}

Example:

curl -X POST https://pcdfitment.codecide.net/api/convert \
  -H "Content-Type: application/json" \
  -d '{"value": 114.3, "from": "metric"}'

Parse

POST /api/parse

Parse a free-text bolt pattern string into structured data. Accepts formats like 5x114.3, 5x4.5, 5 4 1/2, etc.

Request body:

Field	Type	Required	Description
`pattern`	string	Yes	Free-text bolt pattern string.

Success response (200):

{
  "success": true,
  "data": {
    "lugCount": 5,
    "pcdValue": 114.3,
    "detectedUnit": "metric",
    "isValid": true,
    "error": null
  },
  "metadata": { ... }
}

If parsing fails, isValid will be false and error will contain a message.

Example:

curl -X POST https://pcdfitment.codecide.net/api/parse \
  -H "Content-Type: application/json" \
  -d '{"pattern": "5x114.3"}'

Measure

POST /api/measure

Compute the bolt circle diameter (PCD) from a physical stud-to-stud measurement.

Request body:

Field	Type	Required	Description
`lugCount`	integer	Yes	Number of lugs: `3`, `4`, `5`, `6`, `8`, or `10`.
`distance`	number	Yes	Measured distance between adjacent studs (3/5 lugs) or opposite studs (4/6/8/10).
`unit`	string	Yes	Unit of the measurement: `"metric"` or `"imperial"`.

Success response (200):

{
  "success": true,
  "data": {
    "pcdMm": 114.3,
    "pcdInch": 4.5,
    "confidence": "high",
    "formula": "adjacent * 1.7013",
    "closestKnown": "5x114.3",
    "distanceToKnown": 0.0,
    "inAmbiguityZone": false,
    "warnings": []
  },
  "metadata": { ... }
}

confidence can be "high", "medium", or "low". Warnings appear when the measurement falls into an ambiguity zone.

Example:

curl -X POST https://pcdfitment.codecide.net/api/measure \
  -H "Content-Type: application/json" \
  -d '{"lugCount": 5, "distance": 66.97, "unit": "metric"}'

Match

POST /api/match

Compare two bolt patterns and classify their compatibility.

Request body:

Field	Type	Required	Description
`source`	object	Yes	First bolt pattern (see pattern schema).
`target`	object	Yes	Second bolt pattern (see pattern schema).

Pattern schema:

{
  "lugCount": 5,
  "pcd": 114.3,
  "unit": "metric"
}

Success response (200):

{
  "success": true,
  "data": {
    "classification": "exact",
    "lugCountMatch": true,
    "pcdDeltaMm": 0.0,
    "warnings": []
  },
  "metadata": { ... }
}

classification values: "exact", "nearMatch", "incompatible". Warnings may include "nearMatch", "unitMistake", etc.

Example:

curl -X POST https://pcdfitment.codecide.net/api/match \
  -H "Content-Type: application/json" \
  -d '{
    "source": {"lugCount": 5, "pcd": 114.3, "unit": "metric"},
    "target": {"lugCount": 5, "pcd": 4.5, "unit": "imperial"}
  }'

Offset

POST /api/offset

Convert between wheel offset (ET) and backspacing.

Request body:

Field	Type	Required	Description
`wheelWidthInch`	number	Yes	Wheel width in inches (e.g., `8`).
`et`	number	No*	Offset in mm. Provide either `et` or `backspacingMm`.
`backspacingMm`	number	No*	Backspacing in mm. Provide either `et` or `backspacingMm`.

* Exactly one of et or backspacingMm must be provided.

Success response (200):

{
  "success": true,
  "data": {
    "et": 35,
    "backspacingMm": 149.1,
    "wheelWidthInch": 8,
    "warning": null
  },
  "metadata": { ... }
}

A warning string appears if the offset is extreme (|ET| > 60).

Example (ET to backspacing):

curl -X POST https://pcdfitment.codecide.net/api/offset \
  -H "Content-Type: application/json" \
  -d '{"et": 35, "wheelWidthInch": 8}'

Example (backspacing to ET):

curl -X POST https://pcdfitment.codecide.net/api/offset \
  -H "Content-Type: application/json" \
  -d '{"backspacingMm": 149.1, "wheelWidthInch": 8}'

Hub ring

POST /api/hubring

Determine if a hub-centric ring is needed and calculate its dimensions.

Request body:

Field	Type	Required	Description
`hubDiameter`	number	Yes	Vehicle hub diameter in mm.
`wheelBore`	number	Yes	Wheel center bore diameter in mm.

Success response (200):

{
  "success": true,
  "data": {
    "required": true,
    "innerDiameter": 60.1,
    "outerDiameter": 73.1,
    "gapMm": 13.0
  },
  "metadata": { ... }
}

If required is false, the wheel bore already matches the hub.

Example:

curl -X POST https://pcdfitment.codecide.net/api/hubring \
  -H "Content-Type: application/json" \
  -d '{"hubDiameter": 60.1, "wheelBore": 73.1}'

Fitment

POST /api/fitment

Perform a full wheel-to-vehicle fitment analysis. Provide a vehicle profile (or null for a baseline check) and aftermarket wheel specifications.

Request body:

Field	Type	Required	Description
`vehicle`	object or `null`	Yes	Vehicle profile (see schema below) or `null` for a vehicle-less analysis.
`wheelPattern`	object	Yes	Aftermarket wheel bolt pattern (same schema as `/api/match`).
`wheelCenterBore`	number	Yes	Wheel center bore in mm.
`wheelET`	number	Yes	Wheel offset (ET) in mm.
`wheelWidth`	number	Yes	Wheel width in inches.

Vehicle profile schema:

{
  "make": "Toyota",
  "model": "Corolla",
  "year": 2018,
  "lugCount": 5,
  "pcdMm": 114.3,
  "centerBore": 60.1,
  "hubDiameter": 60.1,
  "studThreadSize": "M12x1.5",
  "seatType": "conical",
  "torqueSpecNm": 103,
  "torqueSpecFtLb": 76,
  "etOffset": 45
}

All fields are required when vehicle is not null. The seatType must be one of "conical", "ball", "flat", or "mag".

Success response (200):

{
  "success": true,
  "data": {
    "vehicle": { /* the vehicle profile, or null */ },
    "wheelPattern": { /* the wheel pattern */ },
    "wheelCenterBore": 60.1,
    "wheelET": 45,
    "wheelWidth": 7,
    "fitmentType": "directFit",
    "patternMatch": { /* result from /api/match */ },
    "hubRing": { /* result from /api/hubring */ },
    "adapter": {
      "required": false,
      "minThickness": null,
      "resultingOffset": null,
      "offsetChange": null,
      "safetyNotes": []
    },
    "offsetConversion": { /* result from /api/offset */ },
    "offsetValidation": { /* offset deviation analysis */ },
    "vibrationRisk": { /* risk score and details */ },
    "warnings": []
  },
  "metadata": { ... }
}

fitmentType can be "directFit", "adapterRequired", "hubRingRequired", "incompatible", or "unknown".

Example:

curl -X POST https://pcdfitment.codecide.net/api/fitment \
  -H "Content-Type: application/json" \
  -d '{
    "vehicle": {
      "make": "Toyota",
      "model": "Corolla",
      "year": 2018,
      "lugCount": 5,
      "pcdMm": 114.3,
      "centerBore": 60.1,
      "hubDiameter": 60.1,
      "studThreadSize": "M12x1.5",
      "seatType": "conical",
      "torqueSpecNm": 103,
      "torqueSpecFtLb": 76,
      "etOffset": 45
    },
    "wheelPattern": {"lugCount": 5, "pcd": 114.3, "unit": "metric"},
    "wheelCenterBore": 60.1,
    "wheelET": 45,
    "wheelWidth": 7
  }'

MCP server

For AI tool integration, PCD Fitment also exposes a Model Context Protocol (MCP) server at:

https://pcdfitment.codecide.net/mcp

It provides the same bolt pattern analysis capabilities (conversion, measurement, matching, fitment) as tools, plus access to the pattern and vehicle databases as resources. Use it with any MCP-compatible client to let AI assistants perform wheel fitment calculations directly.