{"openapi":"3.1.0","info":{"title":"Chispections API","version":"1.0.0","description":"Chicago restaurant health inspection data from the City of Chicago Open Data Portal. Public requests are rate-limited; a free API key raises the daily limit.","contact":{"url":"https://chispections.com"},"license":{"name":"Data: City of Chicago Open Data","url":"https://data.cityofchicago.org"}},"servers":[{"url":"https://chispections.com","description":"Production"}],"security":[{"ApiKey":[]}],"paths":{"/v1/restaurants":{"get":{"operationId":"searchRestaurants","summary":"Search restaurants","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":2},"description":"Restaurant name, address, or neighborhood."},{"name":"status","in":"query","schema":{"type":"string","enum":["all","PASS","FAIL","PASS WITH CONDITIONS"],"default":"all"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":20}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Matching restaurants with recent inspection summaries.","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/Restaurant"}},"count":{"type":"integer"},"offset":{"type":"integer"},"limit":{"type":"integer"}}}}}},"400":{"description":"Missing or too-short search query."},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/restaurants/{id}":{"get":{"operationId":"getRestaurant","summary":"Get one restaurant and its latest inspection","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"Restaurant summary and latest inspection.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RestaurantDetail"}}}},"404":{"description":"Restaurant not found."},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/restaurants/{id}/inspections":{"get":{"operationId":"getRestaurantInspections","summary":"Get a restaurant's full inspection history","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"Inspection history.","content":{"application/json":{"schema":{"type":"object","required":["restaurant_id","restaurant_name","inspections"],"properties":{"restaurant_id":{"type":"integer"},"restaurant_name":{"type":"string"},"inspections":{"type":"array","items":{"$ref":"#/components/schemas/Inspection"}}}}}}},"404":{"description":"Restaurant not found."},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/inspections/recent":{"get":{"operationId":"getRecentInspections","summary":"List recently spotted inspections","parameters":[{"name":"days","in":"query","schema":{"type":"integer","minimum":1,"maximum":30,"default":7}},{"name":"status","in":"query","schema":{"type":"string","default":"all"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":20}}],"responses":{"200":{"description":"Recent inspections and parsed violation counts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecentInspectionsResponse"}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/stats":{"get":{"operationId":"getInspectionStats","summary":"Get 30-day inspection statistics","responses":{"200":{"description":"Restaurant count, inspection count, and result counts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatsResponse"}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/keys":{"post":{"operationId":"createApiKey","summary":"Create a free API key","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","minLength":2},"email":{"type":"string","format":"email"}}}}}},"responses":{"201":{"description":"API key created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyResponse"}}}},"400":{"description":"Name is missing or too short."}}}}},"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","in":"header","name":"X-Api-Key","description":"Optional free key. Anonymous requests are limited to 30/day; free keys are limited to 200/day. The key may also be supplied as ?api_key=."}},"responses":{"RateLimited":{"description":"Daily request limit exceeded.","headers":{"Retry-After":{"description":"Retry after the daily limit resets.","schema":{"type":"integer"}}}}},"schemas":{"Restaurant":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"address":{"type":"string","nullable":true},"neighborhood":{"type":"string","nullable":true},"lat":{"type":"number","nullable":true},"lng":{"type":"number","nullable":true},"chain":{"type":"string","nullable":true},"facility_type":{"type":"string","nullable":true},"risk_level":{"type":"string","nullable":true},"current_status":{"type":"string"},"fail_rate":{"type":"string"},"fail_count":{"type":"integer"},"inspection_count":{"type":"integer"},"is_repeat_offender":{"type":"boolean"},"last_inspection_date":{"type":"string","format":"date","nullable":true}}},"RestaurantDetail":{"allOf":[{"$ref":"#/components/schemas/Restaurant"},{"type":"object","properties":{"license_number":{"type":"string","nullable":true},"latest_inspection":{"oneOf":[{"$ref":"#/components/schemas/Inspection"},{"type":"null"}]}}}]},"Inspection":{"type":"object","required":["id","date","result","violations","violation_count","critical_violation_count"],"properties":{"id":{"type":"integer"},"date":{"type":"string","format":"date"},"spotted_at":{"type":"string","format":"date-time","nullable":true},"result":{"type":"string"},"inspection_type":{"type":"string","nullable":true},"violations":{"type":"array","items":{"$ref":"#/components/schemas/Violation"}},"violation_count":{"type":"integer"},"critical_violation_count":{"type":"integer"}}},"RecentInspection":{"type":"object","required":["inspection_id","date","spotted_at","result","inspection_type","restaurant","headline","violation_count","critical_violation_count"],"properties":{"inspection_id":{"type":"integer"},"date":{"type":"string","format":"date"},"spotted_at":{"type":"string","format":"date-time"},"result":{"type":"string"},"inspection_type":{"type":"string","nullable":true},"restaurant":{"oneOf":[{"type":"object","required":["id","name","address","neighborhood","lat","lng"],"properties":{"id":{"type":"integer"},"name":{"type":"string"},"address":{"type":"string","nullable":true},"neighborhood":{"type":"string","nullable":true},"lat":{"type":"number","nullable":true},"lng":{"type":"number","nullable":true}}},{"type":"null"}]},"headline":{"type":"string","nullable":true},"violation_count":{"type":"integer"},"critical_violation_count":{"type":"integer"}}},"RecentInspectionsResponse":{"type":"object","required":["results","count","days","status"],"properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/RecentInspection"}},"count":{"type":"integer"},"days":{"type":"integer","minimum":1,"maximum":30},"status":{"type":"string"}}},"StatsResponse":{"type":"object","required":["restaurants","inspections_30d","result_counts","fail_rate_30d"],"properties":{"restaurants":{"type":"integer"},"inspections_30d":{"type":"integer"},"result_counts":{"type":"object","required":["PASS","FAIL","PASS WITH CONDITIONS"],"properties":{"PASS":{"type":"integer"},"FAIL":{"type":"integer"},"PASS WITH CONDITIONS":{"type":"integer"}}},"fail_rate_30d":{"type":"integer","minimum":0,"maximum":100}}},"ApiKeyResponse":{"type":"object","required":["key","tier","daily_limit","message","docs"],"properties":{"key":{"type":"string","pattern":"^chsp_[a-f0-9]+$"},"tier":{"type":"string","enum":["free"]},"daily_limit":{"type":"integer","minimum":1},"message":{"type":"string"},"docs":{"type":"string","format":"uri"}}},"Violation":{"type":"object","properties":{"title":{"type":"string"},"findings":{"type":"array","items":{"type":"string"}},"is_critical":{"type":"boolean"},"severity_rank":{"type":"integer","nullable":true}}}}}}