{
 "openapi": "3.1.0",
 "info": {
  "title": "local.yohaku.city open data API",
  "version": "1.0.0",
  "description": "Read-only JSON for Japan's 1,741 municipalities (official statistics) and world place pages. No key. CORS open. Rate limit 60 requests/minute per client. Every value carries its source and licence.",
  "contact": {
   "email": "hello@lilambd.com"
  },
  "license": {
   "name": "Per-field source licences (see `sources` in each response)",
   "url": "https://local.yohaku.city/data/"
  }
 },
 "servers": [
  {
   "url": "https://local.yohaku.city"
  }
 ],
 "paths": {
  "/api/v1/towns": {
   "get": {
    "summary": "All 1,741 municipalities (code, name, kana, prefecture, facets available)",
    "responses": {
     "200": {
      "description": "List"
     }
    }
   }
  },
  "/api/v1/towns/{code}": {
   "get": {
    "summary": "One municipality: 33 indicators + 18 derived values (SSDSE-A) and every facet record (postal codes, hazard maps, furusato tax, care insurance, vacant houses, schools, climate normals, tourism, stations)",
    "parameters": [
     {
      "name": "code",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "pattern": "^[0-9]{5}$"
      },
      "example": "13101"
     }
    ],
    "responses": {
     "200": {
      "description": "Profile"
     },
     "404": {
      "description": "Unknown code"
     }
    }
   }
  },
  "/api/v1/towns/{code}/{facet}": {
   "get": {
    "summary": "One facet of one municipality",
    "parameters": [
     {
      "name": "code",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "facet",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "enum": [
        "akiya",
        "eki",
        "furusato",
        "gakko",
        "hazard",
        "kaigo",
        "kanko",
        "kion",
        "yomi",
        "yubin"
       ]
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Facet record"
     }
    }
   }
  },
  "/api/v1/compare": {
   "get": {
    "summary": "Two municipalities side by side (indicators and derived values)",
    "parameters": [
     {
      "name": "a",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "b",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Comparison"
     }
    }
   }
  },
  "/api/v1/facets": {
   "get": {
    "summary": "Facets with their sources and licences",
    "responses": {
     "200": {
      "description": "List"
     }
    }
   }
  },
  "/api/v1/indicators": {
   "get": {
    "summary": "Indicator and derived-value definitions (label, unit, year, formula)",
    "responses": {
     "200": {
      "description": "List"
     }
    }
   }
  },
  "/api/v1/world/countries": {
   "get": {
    "summary": "Countries with world place pages",
    "responses": {
     "200": {
      "description": "List"
     }
    }
   }
  },
  "/api/v1/world/places": {
   "get": {
    "summary": "World places (cities and first-level regions) with pages",
    "parameters": [
     {
      "name": "cc",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "ISO 3166-1 alpha-2 filter"
     }
    ],
    "responses": {
     "200": {
      "description": "List"
     }
    }
   }
  },
  "/api/v1/world/places/{qid}": {
   "get": {
    "summary": "One place: names in many languages, population (Wikidata), coordinates, time zone, monthly climate 2001-2020 (NASA POWER), nearby places",
    "parameters": [
     {
      "name": "qid",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "pattern": "^Q[0-9]+$"
      },
      "example": "Q64"
     }
    ],
    "responses": {
     "200": {
      "description": "Place"
     }
    }
   }
  },
  "/api/v1/search": {
   "get": {
    "summary": "Search municipalities and world places by name (Japanese, kana, English, local name)",
    "parameters": [
     {
      "name": "q",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "limit",
      "in": "query",
      "schema": {
       "type": "integer",
       "default": 10,
       "maximum": 50
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Matches"
     }
    }
   }
  },
  "/api/v1/suggest": {
   "get": {
    "summary": "OpenSearch suggestions (application/x-suggestions+json)",
    "parameters": [
     {
      "name": "q",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "[query, [names], [descriptions], [urls]]"
     }
    }
   }
  }
 }
}