{
    "openapi": "3.1.0",
    "info": {
        "title": "San Antonio Aggressive Driving API",
        "version": "1.0.0",
        "summary": "Police-recorded driving events and resident-reported aggressive driving in San Antonio, served as two separate layers.",
        "description": "Read-only, CORS-enabled, cached JSON.\n\nThis API serves TWO LAYERS THAT MUST NEVER BE ADDED TOGETHER. `\/calls` is an official record: SAPD were dispatched and something happened. `\/reports` is unverified, resident-submitted, and covers what almost nobody phones the police about. They measure different populations, and the gap between them is the only interesting thing about the pairing.\n\nThe calls layer counts only events (crashes, wrong-way drivers), never enforcement actions such as traffic stops, because a ZIP with more stops has more policing rather than worse driving.\n\nThe resident layer collects no license plate, vehicle description, name or photograph: the submission form has no free-text field, so none can exist. Nothing is served finer than a calendar month, roads below a display floor are withheld, and individual reports are never returned.\n\nEvery response carries a `caveats` object stating these conditions.",
        "contact": {
            "name": "BrandShyp",
            "url": "https:\/\/brandshyp.org\/contact-us\/"
        },
        "license": {
            "name": "City of San Antonio open data",
            "url": "https:\/\/data.sanantonio.gov\/"
        }
    },
    "externalDocs": {
        "description": "Human documentation, with the caveats in context",
        "url": "https:\/\/brandshyp.org\/san-antonio-aggressive-driving\/"
    },
    "servers": [
        {
            "url": "https:\/\/brandshyp.org\/api\/v1\/aggressive-driving"
        }
    ],
    "security": [],
    "tags": [
        {
            "name": "official",
            "description": "Police-recorded driving events"
        },
        {
            "name": "resident",
            "description": "Unverified resident reports"
        },
        {
            "name": "meta",
            "description": "Discovery and data quality"
        }
    ],
    "paths": {
        "\/": {
            "get": {
                "summary": "Discovery document",
                "operationId": "getRoot",
                "tags": [
                    "meta"
                ],
                "responses": {
                    "200": {
                        "description": "Both layers described, with their totals, derived live from the files.",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "type": "object",
                                    "required": [
                                        "caveats"
                                    ],
                                    "properties": {
                                        "caveats": {
                                            "$ref": "#\/components\/schemas\/Caveats"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "405": {
                        "description": "Method not allowed. This API is read-only (GET).",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "$ref": "#\/components\/schemas\/Error"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "Dataset temporarily unavailable.",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "$ref": "#\/components\/schemas\/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "\/calls": {
            "get": {
                "summary": "Official driving-event calls",
                "operationId": "getCalls",
                "tags": [
                    "official"
                ],
                "responses": {
                    "200": {
                        "description": "SAPD calls for service by ZIP, month and call type, restricted to events rather than enforcement.",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "type": "object",
                                    "required": [
                                        "caveats"
                                    ],
                                    "properties": {
                                        "caveats": {
                                            "$ref": "#\/components\/schemas\/Caveats"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "405": {
                        "description": "Method not allowed. This API is read-only (GET).",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "$ref": "#\/components\/schemas\/Error"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "Dataset temporarily unavailable.",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "$ref": "#\/components\/schemas\/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "\/reports": {
            "get": {
                "summary": "Resident report totals",
                "operationId": "getReports",
                "tags": [
                    "resident"
                ],
                "responses": {
                    "200": {
                        "description": "Aggregated resident reports, floored and month-grained. Empty of per-road figures until the unlock threshold is met.",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "type": "object",
                                    "required": [
                                        "caveats"
                                    ],
                                    "properties": {
                                        "caveats": {
                                            "$ref": "#\/components\/schemas\/Caveats"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "405": {
                        "description": "Method not allowed. This API is read-only (GET).",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "$ref": "#\/components\/schemas\/Error"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "Dataset temporarily unavailable.",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "$ref": "#\/components\/schemas\/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "\/roads": {
            "get": {
                "summary": "The controlled road vocabulary",
                "operationId": "getRoads",
                "tags": [
                    "meta"
                ],
                "responses": {
                    "200": {
                        "description": "Every classified arterial a report may reference. Local streets are deliberately absent.",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "type": "object",
                                    "required": [
                                        "caveats"
                                    ],
                                    "properties": {
                                        "caveats": {
                                            "$ref": "#\/components\/schemas\/Caveats"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "405": {
                        "description": "Method not allowed. This API is read-only (GET).",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "$ref": "#\/components\/schemas\/Error"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "Dataset temporarily unavailable.",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "$ref": "#\/components\/schemas\/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "\/quality": {
            "get": {
                "summary": "What will make you wrong",
                "operationId": "getQuality",
                "tags": [
                    "meta"
                ],
                "responses": {
                    "200": {
                        "description": "The event\/enforcement split, self-selection, the missing denominator, and everything this API deliberately does not publish.",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "type": "object",
                                    "required": [
                                        "caveats"
                                    ],
                                    "properties": {
                                        "caveats": {
                                            "$ref": "#\/components\/schemas\/Caveats"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "405": {
                        "description": "Method not allowed. This API is read-only (GET).",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "$ref": "#\/components\/schemas\/Error"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "Dataset temporarily unavailable.",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "$ref": "#\/components\/schemas\/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "\/reports.csv": {
            "get": {
                "summary": "Resident aggregate as CSV",
                "operationId": "getReportsCsv",
                "tags": [
                    "resident"
                ],
                "responses": {
                    "200": {
                        "description": "Tidy CSV of the resident aggregate, carrying its caveats as rows.",
                        "content": {
                            "text\/csv": {
                                "schema": {
                                    "type": "string"
                                }
                            }
                        }
                    },
                    "405": {
                        "description": "Method not allowed. This API is read-only (GET).",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "$ref": "#\/components\/schemas\/Error"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "Dataset temporarily unavailable.",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "$ref": "#\/components\/schemas\/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "\/openapi.json": {
            "get": {
                "summary": "This document",
                "operationId": "getOpenapi",
                "tags": [
                    "meta"
                ],
                "responses": {
                    "200": {
                        "description": "OpenAPI 3.1 description.",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "type": "object",
                                    "required": [
                                        "caveats"
                                    ],
                                    "properties": {
                                        "caveats": {
                                            "$ref": "#\/components\/schemas\/Caveats"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "405": {
                        "description": "Method not allowed. This API is read-only (GET).",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "$ref": "#\/components\/schemas\/Error"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "Dataset temporarily unavailable.",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "$ref": "#\/components\/schemas\/Error"
                                }
                            }
                        }
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "Error": {
                "type": "object",
                "required": [
                    "error",
                    "status"
                ],
                "properties": {
                    "error": {
                        "type": "string"
                    },
                    "status": {
                        "type": "integer"
                    }
                }
            },
            "Caveats": {
                "type": "object",
                "description": "The conditions under which these numbers mean anything. Present on every successful JSON response.",
                "properties": {
                    "two_layers_never_summed": {
                        "type": "string"
                    },
                    "reports_are_unverified": {
                        "type": "string"
                    },
                    "self_selection": {
                        "type": "string"
                    },
                    "no_denominator": {
                        "type": "string"
                    },
                    "arterials_only": {
                        "type": "string"
                    },
                    "month_resolution": {
                        "type": "string"
                    },
                    "floored": {
                        "type": "string"
                    },
                    "calls_are_events_only": {
                        "type": "string"
                    }
                }
            }
        }
    }
}