example-vin-search-api.md

VIN to Compatible Parts API Documentation

API Overview

This API allows users to retrieve a list of compatible parts for a vehicle by providing its Vehicle Identification Number (VIN).

Base URL

https://api.example.com/v1

Endpoints

Get Compatible Part IDs

Retrieves a paginated list of compatible part IDs for a given VIN.

• URL: /compatible-parts
• Method: GET
• Auth Required: Yes (API Key)

Parameters

Name	Type	Required	Description
vin	string	Yes	The 17-character Vehicle Identification Number
page	integer	No	Page number (default: 1)
per_page	integer	No	Number of items per page (default: 1000, max: 5000)

Request Example

GET /v1/compatible-parts?vin=JT4RN56S2F0139246&page=1&per_page=1000 HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_API_KEY

Successful Response

• Status Code: 200 OK
• Content Type: application/json

{
  "vin": "JT4RN56S2F0139246",
  "page": 1,
  "per_page": 1000,
  "total_pages": 10,
  "total_items": 10000,
  "compatible_parts": [
    "821415DR40",
    "821415DY90",
    "821415DR41",
    "821415DR41"
    ...
  ]
}

Response Fields

Field	Type	Description
vin	string	The VIN provided in the request
page	integer	Current page number
per_page	integer	Number of items per page
total_pages	integer	Total number of pages
total_items	integer	Total number of compatible parts
compatible_part_ids	array	List of compatible part IDs

Error Responses

• Invalid VIN

  • Status Code: 400 Bad Request
  • Content Type: application/json

  {
    "error": "Invalid VIN provided"
  }

• VIN Not Found

  • Status Code: 404 Not Found
  • Content Type: application/json

  {
    "error": "No vehicle found for the provided VIN"
  }

• Invalid Pagination Parameters

  • Status Code: 400 Bad Request
  • Content Type: application/json

  {
    "error": "Invalid pagination parameters"
  }

• Unauthorized

  • Status Code: 401 Unauthorized
  • Content Type: application/json

  {
    "error": "Invalid or missing API key"
  }

Pagination

The API uses cursor-based pagination to handle large sets of results efficiently. Use the page and per_page parameters to navigate through the results.

• The page parameter specifies which page of results to return.
• The per_page parameter specifies how many items to return per page (max 5000).

Rate Limiting

This API is rate limited to 100 requests per minute per API key. If you exceed this limit, you'll receive a 429 Too Many Requests response.

Authentication

To use this API, you need to include your API key in the Authorization header of each request:

Authorization: Bearer YOUR_API_KEY

To obtain an API key, please contact our support team.

Support

For any questions or issues, please contact our support team at [email protected].