epcdata-api

Ruby REST API for vehicle catalog navigation data.

Stack

• Roda for routing
• Puma for Rack serving
• Nokogiri for HTML parsing
• RSpec for tests

Setup

bundle install
bundle exec puma

The app runs from config.ru.

REST endpoints

The API is mounted directly at the root path. Example base URL:

http://127.0.0.1:9292

GET /health
GET /brands
GET /brands/:id
GET /brands/:id?region=:region
GET /brands/:id/:model
GET /brands/:id/:model/:frame
GET /brands/:id/:model/:frame/:complectation
GET /brands/:id/:model/:frame/:complectation/:group
GET /brands/:id/:model/:frame/:complectation/:group/:section
GET /brands/:id/:model/:frame/:complectation/:group/:section/:pnc

Path parameters:

• :id is the brand slug, such as toyota, honda, kia, or hyundai.
• :model is the model slug from a brand catalog response.
• :frame is the frame slug from a model catalog response.
• :complectation is the complectation slug from a frame catalog response.
• :group is usually engine, chassis, body, electric, or quick.
• :section is the parts section code.
• :pnc is the part number code.
• :region is optional. Supported values are usually japan, europe, general, and usa.

Sample responses

Health

GET /health

{
  "name": "string",
  "status": "string"
}

Brands

GET /brands

[
  {
    "name": "string",
    "slug": "string",
    "endpoint": "string",
    "regions": [
      {
        "name": "string",
        "slug": "string",
        "endpoint": "string"
      }
    ]
  }
]

Brand catalog

GET /brands/:id
GET /brands/:id?region=:region

{
  "brand": "string",
  "slug": "string",
  "endpoint": "string",
  "title": "string",
  "current_region": "string",
  "other_regions": [
    {
      "name": "string",
      "slug": "string",
      "endpoint": "string"
    }
  ],
  "models": [
    {
      "name": "string",
      "slug": "string",
      "endpoint": "string"
    }
  ]
}

Model catalog

GET /brands/:id/:model

{
  "brand": "string",
  "model": "string",
  "slug": "string",
  "endpoint": "string",
  "title": "string",
  "frames": [
    {
      "name": "string",
      "slug": "string",
      "endpoint": "string"
    }
  ]
}

Frame catalog

GET /brands/:id/:model/:frame

{
  "brand": "string",
  "model": "string",
  "frame": "string",
  "slug": "string",
  "endpoint": "string",
  "title": "string",
  "complectations": [
    {
      "name": "string",
      "slug": "string",
      "endpoint": "string",
      "engine": "string",
      "production_period": "string",
      "body": "string",
      "grade": "string",
      "transmission": "string",
      "options": "string"
    }
  ]
}

Complectation catalog

GET /brands/:id/:model/:frame/:complectation

{
  "brand": "string",
  "model": "string",
  "frame": "string",
  "complectation": "string",
  "slug": "string",
  "endpoint": "string",
  "title": "string",
  "details": {
    "production_period": "string",
    "catalog_code": "string",
    "complectation": "string",
    "engine": "string",
    "body": "string",
    "grade": "string",
    "transmission": "string",
    "options": "string"
  },
  "parts_groups": [
    {
      "name": "string",
      "slug": "string",
      "endpoint": "string"
    }
  ],
  "quick_parts": {
    "name": "string",
    "slug": "string",
    "endpoint": "string"
  }
}

Parts group catalog

Valid group slugs are usually engine, chassis, body, electric, and quick.

GET /brands/:id/:model/:frame/:complectation/:group

{
  "brand": "string",
  "model": "string",
  "frame": "string",
  "complectation": "string",
  "group": "string",
  "slug": "string",
  "endpoint": "string",
  "title": "string",
  "sections": [
    {
      "code": "string",
      "name": "string",
      "slug": "string",
      "endpoint": "string",
      "image": "string"
    }
  ],
  "parts": []
}

Quick parts

GET /brands/:id/:model/:frame/:complectation/quick

{
  "brand": "string",
  "model": "string",
  "frame": "string",
  "complectation": "string",
  "group": "string",
  "slug": "string",
  "endpoint": "string",
  "title": "string",
  "sections": [],
  "parts": [
    {
      "group": "string",
      "name": "string",
      "oem": "string",
      "production_period": "string",
      "applicability": "string",
      "advance_order_price": "string",
      "supplier_url": "string"
    }
  ]
}

Part section catalog

GET /brands/:id/:model/:frame/:complectation/:group/:section

{
  "brand": "string",
  "model": "string",
  "frame": "string",
  "complectation": "string",
  "group": "string",
  "section": "string",
  "endpoint": "string",
  "title": "string",
  "schemes": [
    {
      "name": "string",
      "image": "string",
      "full_size_endpoint": "string"
    }
  ],
  "related_parts": [
    {
      "pnc": "string",
      "name": "string",
      "endpoint": "string"
    }
  ]
}

Part detail catalog

GET /brands/:id/:model/:frame/:complectation/:group/:section/:pnc

{
  "brand": "string",
  "model": "string",
  "frame": "string",
  "complectation": "string",
  "group": "string",
  "section": "string",
  "pnc": "string",
  "endpoint": "string",
  "title": "string",
  "selected_parts": [
    {
      "number": "string",
      "pnc": "string",
      "oem": "string",
      "required_per_car": "string",
      "production_period": "string",
      "name": "string",
      "applicability": "string",
      "advance_order_price": "string",
      "supplier_url": "string"
    }
  ],
  "references": [
    {
      "period_marker": "string",
      "frame": "string",
      "note": "string"
    }
  ],
  "schemes": [
    {
      "name": "string",
      "image": "string",
      "full_size_endpoint": "string"
    }
  ],
  "related_parts": [
    {
      "pnc": "string",
      "name": "string",
      "endpoint": "string"
    }
  ]
}

Errors

{
  "error": {
    "type": "string",
    "message": "string"
  }
}

The scraper keeps a small in-memory cache and retries rate-limited requests, but EPC Data may still return 429 when it receives too many requests.

Project structure

controllers/
models/
router/
router/routes/
services/
spec/
utils/
app.rb
config.ru