{"openapi":"3.1.0","info":{"title":"Open Policing Data Hub API","version":"1.0.0","description":"Open read API over problem-oriented policing resources and open policing data: POP guides and projects, ~19,000 US law enforcement agencies with crime trends and NIBRS snapshots, open data sources, police policy portals, and downloadable datasets. Responses are JSON snapshots of the same artifacts the site renders. Open access — no key required; an optional X-API-Key header identifies your client (keys issued on request).","contact":{"url":"https://github.com/michael-zidar/pop_chat/issues"}},"servers":[{"url":"/api/v1"}],"components":{"schemas":{"Envelope":{"type":"object","properties":{"data":{"description":"Endpoint-specific payload."},"meta":{"type":"object","properties":{"generated_at":{"type":"string","description":"Snapshot timestamp of the underlying data."},"count":{"type":"integer"},"total":{"type":"integer"},"next_cursor":{"type":["string","null"],"description":"Opaque cursor for the next page."}}}}},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}},"securitySchemes":{"ApiKey":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Optional. Identifies your client; not required for access."}}},"paths":{"/meta":{"get":{"summary":"API and dataset metadata","description":"Dataset inventory with record counts and snapshot timestamps, plus links to documentation.","parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/guides":{"get":{"summary":"List POP guides","description":"Problem, response, and tool guides.","parameters":[{"name":"q","in":"query","schema":{"type":"string"},"description":"Text match on title, author, description, agency."},{"name":"type","in":"query","schema":{"type":"string"},"description":"Exact resource type, e.g. 'Problem Guide'."},{"name":"year","in":"query","schema":{"type":"integer"}},{"name":"limit","in":"query","schema":{"type":"integer","maximum":100},"description":"Page size (default 25, max 100)."},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Cursor from meta.next_cursor."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/guides/{id}":{"get":{"summary":"Get a guide","description":"Full guide record with markdown and HTML URLs.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/projects":{"get":{"summary":"List POP projects","description":"Conference submissions and case studies.","parameters":[{"name":"q","in":"query","schema":{"type":"string"}},{"name":"agency","in":"query","schema":{"type":"string"},"description":"Substring match on agency name."},{"name":"country","in":"query","schema":{"type":"string"}},{"name":"year","in":"query","schema":{"type":"integer"}},{"name":"limit","in":"query","schema":{"type":"integer","maximum":100},"description":"Page size (default 25, max 100)."},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Cursor from meta.next_cursor."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/projects/{id}":{"get":{"summary":"Get a project","description":"Full project record, including the matched agency ORI when known.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/agencies":{"get":{"summary":"List agencies","description":"Compact directory rows for ~19,000 US law enforcement agencies. Always paginated.","parameters":[{"name":"state","in":"query","schema":{"type":"string"},"description":"Two-letter state abbreviation."},{"name":"q","in":"query","schema":{"type":"string"},"description":"Substring match on name or county."},{"name":"type","in":"query","schema":{"type":"string"},"description":"Agency type, e.g. 'City'."},{"name":"has_trends","in":"query","schema":{"type":"boolean"},"description":"Only agencies with trend snapshots."},{"name":"limit","in":"query","schema":{"type":"integer","maximum":100},"description":"Page size (default 25, max 100)."},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Cursor from meta.next_cursor."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/agencies/{ori}":{"get":{"summary":"Get an agency","description":"Full enriched record: directory data, NIBRS status, LEMAS staffing history, policy portal, open data links, POP submissions.","parameters":[{"name":"ori","in":"path","required":true,"schema":{"type":"string"},"description":"FBI Originating Agency Identifier, e.g. TX2200100."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/agencies/{ori}/trends":{"get":{"summary":"Agency crime trends","description":"Violent crime, property crime, and police employment year series (snapshot subset).","parameters":[{"name":"ori","in":"path","required":true,"schema":{"type":"string"},"description":"FBI Originating Agency Identifier, e.g. TX2200100."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/agencies/{ori}/nibrs":{"get":{"summary":"Agency NIBRS snapshot","description":"Incident-based detail (victims, offenders, relationships, weapons, locations) over complete calendar years for eight offense categories, aggregated from FBI CDE bulk extracts.","parameters":[{"name":"ori","in":"path","required":true,"schema":{"type":"string"},"description":"FBI Originating Agency Identifier, e.g. TX2200100."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/agencies/{ori}/similar":{"get":{"summary":"Comparable agencies","description":"Precomputed nearest neighbors by size, crime mix, rates, and staffing within the same agency class (cosine over z-scored warehouse metrics).","parameters":[{"name":"ori","in":"path","required":true,"schema":{"type":"string"},"description":"FBI Originating Agency Identifier, e.g. TX2200100."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/agencies/search":{"get":{"summary":"Structured agency search","description":"Filter agencies by population served, crime-rate percentile bands, type, state, NIBRS participation, and open-data availability. Rate filters need the live data service; otherwise the response degrades to directory filters (mode: 'degraded').","parameters":[{"name":"state","in":"query","schema":{"type":"string"},"description":"Two-letter state abbreviation."},{"name":"type","in":"query","schema":{"type":"string"},"description":"Agency type, e.g. 'City' or 'University or College'."},{"name":"pop_min","in":"query","schema":{"type":"integer"},"description":"Minimum population served."},{"name":"pop_max","in":"query","schema":{"type":"integer"},"description":"Maximum population served."},{"name":"metric","in":"query","schema":{"type":"string"},"description":"Rate metric, e.g. property_rate_per_1k, bur_victims_per_1k_yr."},{"name":"band","in":"query","schema":{"type":"string","enum":["low","typical","high","very-high"]},"description":"Percentile band for the chosen metric."},{"name":"nibrs","in":"query","schema":{"type":"boolean"}},{"name":"open_data","in":"query","schema":{"type":"boolean"},"description":"Only agencies with confirmed open-data holdings."},{"name":"sort","in":"query","schema":{"type":"string","enum":["population","metric","name"]}},{"name":"order","in":"query","schema":{"type":"string","enum":["asc","desc"]}},{"name":"limit","in":"query","schema":{"type":"integer","maximum":100},"description":"Page size (default 25, max 100)."},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Cursor from meta.next_cursor."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/sources":{"get":{"summary":"List open data sources","description":"Curated source registry with provenance.","parameters":[{"name":"state","in":"query","schema":{"type":"string"}},{"name":"dataset_type","in":"query","schema":{"type":"string"},"description":"Taxonomy value, e.g. USE_OF_FORCE."},{"name":"source_class","in":"query","schema":{"type":"string"},"description":"e.g. api, csv, socrata."},{"name":"limit","in":"query","schema":{"type":"integer","maximum":100},"description":"Page size (default 25, max 100)."},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Cursor from meta.next_cursor."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/sources/{id}":{"get":{"summary":"Get a source","description":"Full registry entry.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/policies":{"get":{"summary":"List policy portals","description":"Public police policy portal directory.","parameters":[{"name":"state","in":"query","schema":{"type":"string"}},{"name":"q","in":"query","schema":{"type":"string"},"description":"Substring match on agency or jurisdiction."},{"name":"limit","in":"query","schema":{"type":"integer","maximum":100},"description":"Page size (default 25, max 100)."},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Cursor from meta.next_cursor."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/datasets":{"get":{"summary":"List datasets","description":"Downloadable dataset files.","parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/search":{"get":{"summary":"Search everything","description":"Lexical search across guides, projects, agencies, sources, policy documents, and datasets.","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"}},{"name":"kind","in":"query","schema":{"type":"string","enum":["guides","projects","agencies","sources","policies","datasets"]}},{"name":"limit","in":"query","schema":{"type":"integer","maximum":100}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}