{
  "openapi": "3.1.0",
  "info": {
    "title": "Search Hawaii Cars API",
    "version": "1.0.0",
    "description": "Read-only access to the used- and new-car inventory of every crawlable dealership in the Hawaiian Islands. Results are de-duplicated by VIN. No authentication, no key, no rate limit beyond ordinary fair use. Prices are dealer-advertised asking prices, exclude tax and fees, and are not offers.",
    "contact": {
      "name": "Tiny Industries",
      "email": "rob@tiny-industries.com",
      "url": "https://searchhawaiicars.com/bot"
    },
    "license": {
      "name": "Free for any use with attribution to searchhawaiicars.com"
    }
  },
  "servers": [
    {
      "url": "https://searchhawaiicars.com"
    }
  ],
  "paths": {
    "/api/listings": {
      "get": {
        "operationId": "searchListings",
        "summary": "Search vehicles",
        "description": "Filter the 8,334 vehicles currently for sale. All parameters are optional and combine with AND. Comma-separated values within one parameter combine with OR.",
        "parameters": [
          {
            "name": "island",
            "in": "query",
            "description": "Comma-separated island slugs.",
            "schema": {
              "type": "string",
              "enum": [
                "oahu",
                "maui",
                "hawaii",
                "kauai",
                "molokai",
                "lanai"
              ]
            },
            "example": "maui,oahu"
          },
          {
            "name": "make",
            "in": "query",
            "description": "Manufacturer, exact match.",
            "schema": {
              "type": "string"
            },
            "example": "Toyota"
          },
          {
            "name": "model",
            "in": "query",
            "description": "Free-text model search; also matches trim.",
            "schema": {
              "type": "string"
            },
            "example": "Tacoma"
          },
          {
            "name": "dealer",
            "in": "query",
            "description": "Dealer hostname.",
            "schema": {
              "type": "string"
            },
            "example": "alohakiamaui.com"
          },
          {
            "name": "min_price",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "max_price",
            "in": "query",
            "schema": {
              "type": "integer"
            },
            "example": 25000
          },
          {
            "name": "min_year",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "max_year",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "max_mileage",
            "in": "query",
            "schema": {
              "type": "integer"
            },
            "example": 60000
          },
          {
            "name": "condition",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "new",
                "used"
              ]
            }
          },
          {
            "name": "powertrain",
            "in": "query",
            "description": "Comma-separated.",
            "schema": {
              "type": "string",
              "enum": [
                "gas",
                "hybrid",
                "plug-in hybrid",
                "electric",
                "diesel"
              ]
            },
            "example": "electric,plug-in hybrid"
          },
          {
            "name": "drive",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "awd",
                "4wd",
                "fwd",
                "rwd"
              ]
            }
          },
          {
            "name": "trans",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "automatic",
                "manual",
                "cvt",
                "dct"
              ]
            }
          },
          {
            "name": "color",
            "in": "query",
            "description": "Normalised exterior colour family.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "third_row",
            "in": "query",
            "description": "Set to 1 for vehicles with third-row seating.",
            "schema": {
              "type": "integer",
              "enum": [
                1
              ]
            }
          },
          {
            "name": "price_drop",
            "in": "query",
            "description": "Set to 1 for vehicles whose asking price has fallen since we first saw them.",
            "schema": {
              "type": "integer",
              "enum": [
                1
              ]
            }
          },
          {
            "name": "newly_listed",
            "in": "query",
            "description": "Set to 1 for vehicles first seen in the last 7 days.",
            "schema": {
              "type": "integer",
              "enum": [
                1
              ]
            }
          },
          {
            "name": "sort",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "price",
                "price_desc",
                "mileage",
                "year_desc",
                "newest",
                "days_on_lot"
              ],
              "default": "price"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "maximum": 100,
              "default": 25
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Matching vehicles, cheapest first by default.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResult"
                }
              }
            }
          }
        }
      }
    },
    "/api/listings/{vin}": {
      "get": {
        "operationId": "getVehicle",
        "summary": "One vehicle by VIN, with price history and every dealer listing it",
        "parameters": [
          {
            "name": "vin",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Vehicle detail, price history, and other rooftops listing the same VIN."
          },
          "404": {
            "description": "No active listing with that VIN."
          }
        }
      }
    },
    "/api/facets": {
      "get": {
        "operationId": "getFacets",
        "summary": "Valid filter values with live counts",
        "description": "Accepts the same filters as /api/listings and returns the remaining choices. Call this before searching to learn what values exist.",
        "responses": {
          "200": {
            "description": "Makes, body styles, islands, years, powertrains, drivetrains, transmissions, colours, seating and condition, each with a count."
          }
        }
      }
    },
    "/api/summary": {
      "get": {
        "operationId": "getSummary",
        "summary": "Totals by island and make",
        "responses": {
          "200": {
            "description": "Vehicle counts, dealer counts and average prices."
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "SearchResult": {
        "type": "object",
        "properties": {
          "total": {
            "type": "integer",
            "description": "Total matches before limit/offset."
          },
          "listings": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Vehicle"
            }
          }
        }
      },
      "Vehicle": {
        "type": "object",
        "properties": {
          "vin": {
            "type": "string"
          },
          "year": {
            "type": "integer"
          },
          "make": {
            "type": "string"
          },
          "model": {
            "type": "string"
          },
          "trim": {
            "type": "string"
          },
          "price": {
            "type": "number",
            "description": "Dealer asking price in USD, excluding tax and fees."
          },
          "msrp": {
            "type": "number",
            "nullable": true
          },
          "mileage": {
            "type": "integer",
            "nullable": true
          },
          "condition": {
            "type": "string",
            "enum": [
              "new",
              "used"
            ]
          },
          "body_style": {
            "type": "string"
          },
          "powertrain": {
            "type": "string"
          },
          "drive": {
            "type": "string"
          },
          "trans": {
            "type": "string"
          },
          "color": {
            "type": "string"
          },
          "third_row": {
            "type": "integer",
            "nullable": true
          },
          "dealer": {
            "type": "string"
          },
          "dealer_host": {
            "type": "string"
          },
          "dealer_phone": {
            "type": "string"
          },
          "island": {
            "type": "string",
            "enum": [
              "oahu",
              "maui",
              "hawaii",
              "kauai",
              "molokai",
              "lanai"
            ]
          },
          "vdp_url": {
            "type": "string",
            "description": "The dealer's own listing page. Always link here."
          },
          "image": {
            "type": "string",
            "nullable": true
          },
          "first_seen": {
            "type": "string",
            "format": "date-time",
            "description": "When we first saw this car; days-on-lot is derived from it."
          },
          "last_checked": {
            "type": "string",
            "format": "date-time"
          },
          "price_drop": {
            "type": "integer",
            "description": "1 if the asking price has fallen since first seen."
          },
          "other_locations": {
            "type": "integer",
            "description": "How many other rooftops list this same VIN."
          }
        }
      }
    }
  }
}