{
  "openapi": "3.0.3",
  "info": {
    "title": "School District Finder API",
    "description": "Free JSON API returning US school district data by zip code. Covers 33,559 zip codes across all 50 states. Source: NCES Common Core of Data 2024-2025. License: CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/).",
    "version": "1.0.0",
    "contact": {
      "name": "SchoolDistrictFinder",
      "url": "https://www.schooldistrictfinder.us",
      "email": "contact@schooldistrictfinder.us"
    },
    "license": {
      "name": "CC BY 4.0",
      "url": "https://creativecommons.org/licenses/by/4.0/"
    }
  },
  "servers": [
    {
      "url": "https://api.schooldistrictfinder.us",
      "description": "Production API"
    }
  ],
  "paths": {
    "/zip/{zip}.json": {
      "get": {
        "summary": "Get school district by zip code",
        "description": "Returns school district data for a single US zip code.",
        "operationId": "getDistrictByZip",
        "parameters": [
          {
            "name": "zip",
            "in": "path",
            "required": true,
            "description": "5-digit US zip code (e.g. 90210)",
            "schema": {
              "type": "string",
              "pattern": "^[0-9]{5}$",
              "example": "90210"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "School district data for the zip code",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DistrictRecord"
                },
                "example": {
                  "zip": "90210",
                  "district": "Beverly Hills Unified School District",
                  "city": "Beverly Hills",
                  "state": "CA",
                  "county": "Los Angeles County",
                  "rating": 9,
                  "rating_label": "Excellent",
                  "students": "3,500",
                  "schools": "6",
                  "per_pupil": "$21,000/yr",
                  "grade_span": "Kindergarten \u2013 12th",
                  "phone": "(310)551-5100",
                  "website": "http://www.bhusd.org",
                  "page_url": "https://www.schooldistrictfinder.us/zip/90210/",
                  "source": "NCES Common Core of Data 2024-2025",
                  "source_url": "https://nces.ed.gov/ccd/",
                  "license": "https://creativecommons.org/licenses/by/4.0/",
                  "updated": "2026-08-11"
                }
              }
            }
          },
          "404": {
            "description": "Zip code not found in dataset"
          }
        }
      }
    },
    "/state/{state}.json": {
      "get": {
        "summary": "Get all districts in a state",
        "description": "Returns an array of all zip code records for a given US state.",
        "operationId": "getDistrictsByState",
        "parameters": [
          {
            "name": "state",
            "in": "path",
            "required": true,
            "description": "Two-letter US state abbreviation, uppercase (e.g. CA, TX, NY)",
            "schema": {
              "type": "string",
              "pattern": "^[A-Z]{2}$",
              "example": "CA"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Array of district records for the state",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "state": {
                      "type": "string",
                      "example": "CA"
                    },
                    "count": {
                      "type": "integer",
                      "example": 1742
                    },
                    "records": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/DistrictRecord"
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "State abbreviation not found"
          }
        }
      }
    },
    "/bulk/all-districts.json": {
      "get": {
        "summary": "Bulk download \u2014 all districts as JSON",
        "description": "Returns all 33,559 zip code records in a single JSON file. Suitable for RAG ingestion, ML training, or offline analysis.",
        "operationId": "getAllDistrictsJson",
        "responses": {
          "200": {
            "description": "All district records",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "total": {
                      "type": "integer",
                      "example": 33559
                    },
                    "source": {
                      "type": "string"
                    },
                    "license": {
                      "type": "string"
                    },
                    "updated": {
                      "type": "string"
                    },
                    "records": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/DistrictRecord"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/bulk/all-districts.csv": {
      "get": {
        "summary": "Bulk download \u2014 all districts as CSV",
        "description": "Returns all 33,559 zip code records as a CSV file. Columns: zip, district, city, state, county, rating, rating_label, students, schools, per_pupil, grade_span, phone, website, page_url, updated.",
        "operationId": "getAllDistrictsCsv",
        "responses": {
          "200": {
            "description": "CSV file of all district records",
            "content": {
              "text/csv": {}
            }
          }
        }
      }
    },
    "/index.json": {
      "get": {
        "summary": "Master index of all covered zip codes",
        "description": "Returns a list of all 33,559 zip codes covered by this API.",
        "operationId": "getIndex",
        "responses": {
          "200": {
            "description": "Array of zip code strings",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  },
                  "example": [
                    "00501",
                    "00601",
                    "00602"
                  ]
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "DistrictRecord": {
        "type": "object",
        "properties": {
          "zip": {
            "type": "string",
            "description": "5-digit US zip code"
          },
          "district": {
            "type": "string",
            "description": "Full official district name"
          },
          "city": {
            "type": "string",
            "description": "Primary city served"
          },
          "state": {
            "type": "string",
            "description": "2-letter state abbreviation"
          },
          "county": {
            "type": "string",
            "description": "County name"
          },
          "rating": {
            "type": "integer",
            "description": "District rating 1-10 (10=best)",
            "minimum": 1,
            "maximum": 10
          },
          "rating_label": {
            "type": "string",
            "description": "Rating label (e.g. Excellent, Good, Average, Below Average, Poor)"
          },
          "students": {
            "type": "string",
            "description": "Total student enrollment (formatted string)"
          },
          "schools": {
            "type": "string",
            "description": "Number of schools in district"
          },
          "per_pupil": {
            "type": "string",
            "description": "Per-pupil spending (formatted string, e.g. '$12,000/yr')"
          },
          "grade_span": {
            "type": "string",
            "description": "Grade range served (e.g. 'Kindergarten \u2013 12th')"
          },
          "phone": {
            "type": "string",
            "description": "District main phone number"
          },
          "website": {
            "type": "string",
            "description": "District official website URL"
          },
          "page_url": {
            "type": "string",
            "description": "SchoolDistrictFinder page for this zip"
          },
          "source": {
            "type": "string",
            "description": "Data source name"
          },
          "source_url": {
            "type": "string",
            "description": "Data source URL"
          },
          "license": {
            "type": "string",
            "description": "Data license URL (CC BY 4.0)"
          },
          "updated": {
            "type": "string",
            "description": "Last updated date (YYYY-MM-DD)"
          }
        }
      }
    }
  }
}