{
  "openapi": "3.1.0",
  "info": {
    "title": "全国Q地図 API",
    "description": "全国Q地図が提供するAPIです。各APIのレスポンスには全国Q地図の表示用・埋め込み用URLが含まれます。\n\n## 提供API\n\n- **ジオコーダAPI** (`/geocode.php`): 住所から経緯度を検索\n- **標高API** (`/elevation.php`): 経緯度から標高を取得\n\n## 利用条件\n\n本APIの結果を利用する際は、以下の条件に従ってください。\n\n- **地図に表示する場合**: 全国Q地図（qchizu.jp）の埋め込み地図を使用してください\n- **地図に表示しない場合**（データ保持等）: 全国Q地図の表示用URL（`links.qchizu_map`）または埋め込み用URL（`links.qchizu_embed`）を必ず保持・提示してください\n\n## アクセス制限\n\n### CORS（クロスオリジン）\n\nブラウザからのリクエストは、許可されたオリジンのみ `Access-Control-Allow-Origin` ヘッダーが付与されます。許可オリジン以外からのブラウザリクエストはCORSポリシーによりブロックされます。サーバーサイド（cURL、fetch等）からのリクエストにはCORS制限は適用されません。\n\n### レート制限\n\n許可オリジン以外からのリクエストには、IPアドレスベースのレート制限が適用されます（300リクエスト/分、API毎に独立カウント）。制限を超えた場合は `429 Too Many Requests` が返されます。許可オリジンからのリクエストにはレート制限は適用されません。",
    "version": "1.1.0",
    "contact": {
      "name": "全国Q地図",
      "url": "https://qchizu.jp/"
    }
  },
  "servers": [
    {
      "url": "https://api.qchizu.jp",
      "description": "本番環境"
    }
  ],
  "paths": {
    "/geocode.php": {
      "get": {
        "operationId": "geocode",
        "summary": "住所ジオコーディング",
        "description": "住所文字列から経緯度を検索し、全国Q地図の表示用URLと埋め込み用URLを返します。新旧バックエンド並行運用期間中は `version` パラメータで挙動を切替可能です（Issue #49）。",
        "parameters": [
          {
            "name": "address",
            "in": "query",
            "required": true,
            "description": "検索する住所文字列（最大500文字）",
            "schema": {
              "type": "string",
              "maxLength": 500
            },
            "example": "東京都千代田区永田町1-7-1"
          },
          {
            "name": "target",
            "in": "query",
            "required": false,
            "description": "検索対象の住所種別。all: 全種別、residential: 住居表示の住所のみ、parcel: 地番の住所のみ。version=2の場合、residentialはallと同義に扱われます（独自版ジオコーダは住居表示・地番を自動選択するため単独指定の意味を持ちません）",
            "schema": {
              "type": "string",
              "enum": ["all", "residential", "parcel"],
              "default": "all"
            }
          },
          {
            "name": "fuzzy",
            "in": "query",
            "required": false,
            "description": "ファジーマッチ用ワイルドカード文字（印刷可能な1文字のみ）。version=1（既定）でのみ有効です。version=2では無視されます",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 1
            }
          },
          {
            "name": "version",
            "in": "query",
            "required": false,
            "description": "バックエンドAPIバージョン切替用パラメータ（新旧バックエンド並行運用期間中の互換性維持のため。Issue #49）。未指定または \"1\"/\"v1\" は現行の旧ABR形式（GeocodeResponse）を返します。\"2\"/\"v2\" を指定すると独自版ジオコーダのリッチ形式（GeocodeResponseV2）を返します。値は大文字小文字を区別します。移行完了後は既定がv2へ切り替わり、旧形式（v1）は廃止予定です",
            "schema": {
              "type": "string",
              "enum": ["1", "v1", "2", "v2"],
              "default": "1"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "ジオコーディング結果。version=1（既定・未指定含む）は GeocodeResponse、version=2 は GeocodeResponseV2 を返します",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    { "$ref": "#/components/schemas/GeocodeResponse" },
                    { "$ref": "#/components/schemas/GeocodeResponseV2" }
                  ]
                },
                "examples": {
                  "v1_legacy": {
                    "summary": "version=1（既定・旧ABR形式）",
                    "value": {
                      "results": [
                        {
                          "query": {
                            "input": "東京都千代田区永田町1-7-1"
                          },
                          "result": {
                            "output": "東京都千代田区永田町一丁目7-1",
                            "others": ["-1"],
                            "score": 0.82,
                            "match_level": "residential_block",
                            "coordinate_level": "residential_block",
                            "lat": 35.674571,
                            "lon": 139.744934,
                            "lg_code": "131016",
                            "machiaza_id": "0005001",
                            "rsdt_addr_flg": 1,
                            "blk_id": "007",
                            "rsdt_id": null,
                            "rsdt2_id": null,
                            "prc_id": null,
                            "pref": "東京都",
                            "county": null,
                            "city": "千代田区",
                            "ward": null,
                            "oaza_cho": "永田町",
                            "chome": "一丁目",
                            "koaza": null,
                            "blk_num": "7",
                            "rsdt_num": null,
                            "rsdt_num2": null,
                            "prc_num1": null,
                            "prc_num2": null,
                            "prc_num3": null
                          },
                          "links": {
                            "qchizu_map": "https://qchizu.jp/maps/#17/35.674571/139.744934/",
                            "qchizu_embed": "https://qchizu.jp/maps/index_pm.html#17/35.674571/139.744934/"
                          }
                        }
                      ],
                      "attribution": "住所データ: デジタル庁 アドレス・ベース・レジストリ / 地図: 全国Q地図 (https://qchizu.jp)",
                      "usage_policy": "本APIの結果を利用する際は、地図に表示する場合は全国Q地図（qchizu.jp）の埋め込み地図を使用してください。地図に表示しない場合（データ保持等）は、全国Q地図の表示用URL（links.qchizu_map）または埋め込み用URL（links.qchizu_embed）を必ず保持・提示してください。",
                      "links": {
                        "qchizu_top": "https://qchizu.jp/",
                        "qchizu_maps": "https://qchizu.jp/maps/",
                        "documentation": "https://api.qchizu.jp/openapi.json"
                      }
                    }
                  },
                  "v2_rich": {
                    "summary": "version=2（独自版リッチ形式）",
                    "value": {
                      "query": "福岡県北九州市門司区清滝1丁目1-1",
                      "version": "0.1.1",
                      "abr_data_date": "2026-06-01",
                      "candidates": [
                        {
                          "matched": "福岡県北九州市門司区清滝一丁目1番1号",
                          "geocoding_matched": "福岡県北九州市門司区清滝一丁目1番1号",
                          "furigana": "フクオカケンキタキュウシュウシモジクキヨタキイッチョウメ1バン1ゴウ",
                          "trailing": "",
                          "unused": "",
                          "supplemented": "",
                          "match_level": "jukyo",
                          "location_level": "jukyo",
                          "position": {
                            "lat": 33.94166,
                            "lon": 130.959553
                          },
                          "pref_code": "40",
                          "city_code": "40101",
                          "machi_aza_id": "0036001",
                          "has_parcel_data": false,
                          "has_rsdt_data": true,
                          "parcel_id": null,
                          "blk_id": "001",
                          "rsdt_id": "001",
                          "address_components": {
                            "pref": "福岡県",
                            "county": null,
                            "city": "北九州市",
                            "ward": "門司区",
                            "oaza_cho": "清滝",
                            "chome": "一丁目",
                            "koaza": null,
                            "chiban": null,
                            "gaiku": "1",
                            "jukyo": "1"
                          },
                          "links": {
                            "qchizu_map": "https://qchizu.jp/maps/#17/33.941660/130.959553/",
                            "qchizu_embed": "https://qchizu.jp/maps/index_pm.html#17/33.941660/130.959553/"
                          }
                        }
                      ],
                      "truncated": false,
                      "attribution": "住所データ: デジタル庁 アドレス・ベース・レジストリ / 地図: 全国Q地図 (https://qchizu.jp)",
                      "usage_policy": "本APIの結果を利用する際は、地図に表示する場合は全国Q地図（qchizu.jp）の埋め込み地図を使用してください。地図に表示しない場合（データ保持等）は、全国Q地図の表示用URL（links.qchizu_map）または埋め込み用URL（links.qchizu_embed）を必ず保持・提示してください。",
                      "links": {
                        "qchizu_top": "https://qchizu.jp/",
                        "qchizu_maps": "https://qchizu.jp/maps/",
                        "documentation": "https://api.qchizu.jp/openapi.json"
                      }
                    }
                  }
                }
              }
            }
          },
          "405": {
            "description": "許可されていないHTTPメソッド（GET以外）",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Method Not Allowed"
                }
              }
            }
          },
          "400": {
            "description": "リクエストパラメータエラー",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "missing_address": {
                    "summary": "address未指定",
                    "value": { "error": "address parameter is required" }
                  },
                  "address_too_long": {
                    "summary": "address文字数超過",
                    "value": { "error": "address parameter is too long (max 500 characters)" }
                  },
                  "invalid_target": {
                    "summary": "無効なtarget",
                    "value": { "error": "Invalid target parameter. Must be one of: all, residential, parcel" }
                  },
                  "invalid_fuzzy": {
                    "summary": "無効なfuzzy",
                    "value": { "error": "fuzzy parameter must be exactly 1 printable character" }
                  },
                  "unsupported_version": {
                    "summary": "未対応のversion",
                    "value": { "error": "Invalid version parameter. Supported values: 1, v1, 2, v2" }
                  },
                  "invalid_request_v2": {
                    "summary": "独自版ジオコーダの入力検証エラー（version=2）",
                    "value": { "error": "Invalid request" }
                  }
                }
              }
            }
          },
          "429": {
            "description": "レート制限超過。許可オリジン以外からのリクエストに対し、IPアドレスごとに300リクエスト/分の制限が適用されます。許可オリジンからのリクエストにはレート制限は適用されません",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "サーバー内部エラー（設定ファイル不備等）",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "502": {
            "description": "ジオコーダサービスのエラー（接続不可、無効なレスポンス等。ジオコーダが返したHTTPステータスコードがそのまま返される場合もある）",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/elevation.php": {
      "get": {
        "operationId": "getElevation",
        "summary": "標高取得",
        "description": "指定した経緯度の標高を取得します（日本国内の陸上のみ対応）。標高タイル（数値PNG/WebP）からピクセル値を読み取り、標高値をメートル単位で返します。DEM1A（1mメッシュ）→ DEM5A/5B/5C（5mメッシュ）→ DEM10B（10mメッシュ）の順に高精度なソースから試行し、最初に有効な値が得られたソースの標高を返却します。日本国外や海上の座標を指定した場合、result.elevationとresult.sourceはnullになります。レスポンスには全国Q地図の地形表示URL（淡色地図＋赤色立体地図＋等高線）が含まれます。回答にはlinks.qchizu_mapリンクを必ず含めてください。",
        "parameters": [
          {
            "name": "lat",
            "in": "query",
            "required": true,
            "description": "緯度（WGS84、度数法、20〜46。日本国内の範囲に制限）",
            "schema": {
              "type": "number",
              "minimum": 20,
              "maximum": 46
            },
            "example": 35.681236
          },
          {
            "name": "lon",
            "in": "query",
            "required": true,
            "description": "経度（WGS84、度数法、122〜154。日本国内の範囲に制限）",
            "schema": {
              "type": "number",
              "minimum": 122,
              "maximum": 154
            },
            "example": 139.767125
          }
        ],
        "responses": {
          "200": {
            "description": "標高取得結果。標高データが存在しない地点（海上・日本国外や海上等）の場合、result.elevationとresult.sourceがnullになります",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ElevationResponse"
                },
                "example": {
                  "result": {
                    "elevation": 3.22,
                    "source": {
                      "name": "DEM5A",
                      "description": "基盤地図情報 数値標高モデル（5mメッシュ・航空レーザ測量）",
                      "zoom": 15,
                      "tile_size": 256,
                      "is_jgd2024": false,
                      "attribution": "地理院タイル"
                    }
                  },
                  "query": {
                    "lat": 35.681236,
                    "lon": 139.767125
                  },
                  "links": {
                    "qchizu_map": "https://qchizu.jp/maps/#17/35.681236/139.767125/&base=pale&ls=03_dem_52_gsi_all_2026_1_01_dem2rrim%7C03_dem_52_gsi_all_2026_1_01_dem2contour&disp=11",
                    "qchizu_embed": "https://qchizu.jp/maps/index_pm.html#17/35.681236/139.767125/&base=pale&ls=03_dem_52_gsi_all_2026_1_01_dem2rrim%7C03_dem_52_gsi_all_2026_1_01_dem2contour&disp=11"
                  },
                  "attribution": "標高データ: 国土地理院 / Q地図タイル(測量法に基づく国土地理院長承認) / 地図: 全国Q地図 (https://qchizu.jp)",
                  "usage_policy": "本APIの結果を利用する際は、地図に表示する場合は全国Q地図（qchizu.jp）の埋め込み地図を使用してください。地図に表示しない場合（データ保持等）は、全国Q地図の表示用URL（links.qchizu_map）または埋め込み用URL（links.qchizu_embed）を必ず保持・提示してください。",
                  "links_global": {
                    "qchizu_top": "https://qchizu.jp/",
                    "qchizu_maps": "https://qchizu.jp/maps/",
                    "documentation": "https://api.qchizu.jp/openapi.json"
                  }
                }
              }
            }
          },
          "400": {
            "description": "リクエストパラメータエラー",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "missing_params": {
                    "summary": "lat/lon未指定",
                    "value": { "error": "lat and lon parameters are required" }
                  },
                  "not_numeric": {
                    "summary": "数値でない値",
                    "value": { "error": "lat and lon must be numeric values" }
                  },
                  "lat_out_of_range": {
                    "summary": "緯度が範囲外",
                    "value": { "error": "lat must be between 20 and 46 (Japan)" }
                  },
                  "lon_out_of_range": {
                    "summary": "経度が範囲外",
                    "value": { "error": "lon must be between 122 and 154 (Japan)" }
                  }
                }
              }
            }
          },
          "405": {
            "description": "許可されていないHTTPメソッド（GET以外）",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Method Not Allowed"
                }
              }
            }
          },
          "429": {
            "description": "レート制限超過。許可オリジン以外からのリクエストに対し、IPアドレスごとに300リクエスト/分の制限が適用されます。許可オリジンからのリクエストにはレート制限は適用されません",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "サーバー内部エラー（設定ファイル不備等）",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "GeocodeResponse": {
        "type": "object",
        "required": ["results", "attribution", "usage_policy", "links"],
        "properties": {
          "results": {
            "type": "array",
            "description": "ジオコーディング結果の配列",
            "items": {
              "$ref": "#/components/schemas/GeocodeResult"
            }
          },
          "attribution": {
            "type": "string",
            "description": "データの出典表示"
          },
          "usage_policy": {
            "type": "string",
            "description": "本APIの利用条件。地図表示には全国Q地図の埋め込みを使用し、データ保持時はQ地図URLを保持・提示すること"
          },
          "links": {
            "type": "object",
            "description": "全国Q地図の関連リンク",
            "properties": {
              "qchizu_top": {
                "type": "string",
                "format": "uri",
                "description": "全国Q地図トップページURL"
              },
              "qchizu_maps": {
                "type": "string",
                "format": "uri",
                "description": "全国Q地図の地図ページURL"
              },
              "documentation": {
                "type": "string",
                "format": "uri",
                "description": "本APIのOpenAPI仕様書URL"
              }
            }
          }
        }
      },
      "GeocodeResult": {
        "type": "object",
        "required": ["query", "result", "links"],
        "properties": {
          "query": {
            "type": "object",
            "description": "入力クエリ情報",
            "properties": {
              "input": {
                "type": "string",
                "description": "入力した住所文字列"
              }
            }
          },
          "result": {
            "$ref": "#/components/schemas/AddressResult"
          },
          "links": {
            "type": ["object", "null"],
            "description": "全国Q地図へのリンク。座標が不明な場合はnull",
            "properties": {
              "qchizu_map": {
                "type": "string",
                "format": "uri",
                "description": "全国Q地図で当該地点を表示するURL。ブラウザで開くと地図上に地点が表示される"
              },
              "qchizu_embed": {
                "type": "string",
                "format": "uri",
                "description": "全国Q地図の埋め込み用URL。iframeのsrcに指定して地図を埋め込める"
              }
            }
          }
        }
      },
      "AddressResult": {
        "type": "object",
        "required": ["output", "others", "score", "match_level", "coordinate_level"],
        "description": "ジオコーディング結果の詳細（デジタル庁ABRジオコーダー準拠）",
        "properties": {
          "output": {
            "type": "string",
            "description": "正規化された住所文字列"
          },
          "others": {
            "type": "array",
            "items": { "type": "string" },
            "description": "マッチしなかった住所の残り部分"
          },
          "score": {
            "type": "number",
            "minimum": 0,
            "maximum": 1,
            "description": "マッチスコア（0〜1、1が完全一致）"
          },
          "match_level": {
            "type": "string",
            "description": "住所のマッチ精度レベル（unknown: 不明, prefecture: 都道府県, city: 郡 / 市区町村, machiaza: 大字・町, machiaza_detail: 丁目・小字, residential_block: 街区符号, residential_detail: 住居番号, parcel: 地番）",
            "enum": ["error", "unknown", "prefecture", "city", "machiaza", "machiaza_detail", "residential_block", "residential_detail", "parcel"]
          },
          "coordinate_level": {
            "type": "string",
            "description": "座標の精度レベル（unknown: 不明, prefecture: 都道府県, city: 郡 / 市区町村, machiaza: 大字・町, machiaza_detail: 丁目・小字, residential_block: 街区符号, residential_detail: 住居番号, parcel: 地番）。match_levelとは異なる場合がある（例: 住所は町字まで特定できたが座標は市区町村レベルのみ等）。この値に基づいてQ地図URLのズームレベルが自動決定される（prefecture→8, city→12, machiaza→15, residential/parcel→17）",
            "enum": ["error", "unknown", "prefecture", "city", "machiaza", "machiaza_detail", "residential_block", "residential_detail", "parcel"]
          },
          "lat": {
            "type": ["number", "null"],
            "description": "緯度（WGS84、度数法）。座標不明の場合はnull"
          },
          "lon": {
            "type": ["number", "null"],
            "description": "経度（WGS84、度数法）。座標不明の場合はnull"
          },
          "lg_code": {
            "type": ["string", "null"],
            "description": "全国地方公共団体コード（6桁）"
          },
          "machiaza_id": {
            "type": ["string", "null"],
            "description": "町字ID"
          },
          "rsdt_addr_flg": {
            "type": "integer",
            "enum": [-1, 0, 1],
            "description": "住居表示フラグ（1: 住居表示、0: 地番、-1: 不明）。マッチレベルが都道府県・市区町村のみの場合はフィールド自体が省略されることがある"
          },
          "blk_id": {
            "type": ["string", "null"],
            "description": "街区ID"
          },
          "rsdt_id": {
            "type": ["string", "null"],
            "description": "住居ID"
          },
          "rsdt2_id": {
            "type": ["string", "null"],
            "description": "住居ID2（枝番）"
          },
          "prc_id": {
            "type": ["string", "null"],
            "description": "地番ID"
          },
          "pref": {
            "type": ["string", "null"],
            "description": "都道府県名"
          },
          "county": {
            "type": ["string", "null"],
            "description": "郡名"
          },
          "city": {
            "type": ["string", "null"],
            "description": "市区町村名"
          },
          "ward": {
            "type": ["string", "null"],
            "description": "政令指定都市の区名"
          },
          "oaza_cho": {
            "type": ["string", "null"],
            "description": "大字・町名"
          },
          "chome": {
            "type": ["string", "null"],
            "description": "丁目"
          },
          "koaza": {
            "type": ["string", "null"],
            "description": "小字名"
          },
          "blk_num": {
            "type": ["string", "null"],
            "description": "街区符号"
          },
          "rsdt_num": {
            "type": ["string", "null"],
            "description": "住居番号"
          },
          "rsdt_num2": {
            "type": ["string", "null"],
            "description": "住居番号2（枝番）"
          },
          "prc_num1": {
            "type": ["string", "null"],
            "description": "地番1"
          },
          "prc_num2": {
            "type": ["string", "null"],
            "description": "地番2（枝番）"
          },
          "prc_num3": {
            "type": ["string", "null"],
            "description": "地番3（枝番）"
          }
        }
      },
      "GeocodeResponseV2": {
        "type": "object",
        "description": "version=2/v2 指定時の独自版ジオコーダのリッチレスポンス形式",
        "required": ["query", "version", "candidates", "attribution", "usage_policy", "links"],
        "properties": {
          "query": {
            "type": "string",
            "description": "入力した住所・所在地文字列（エコーバック）"
          },
          "version": {
            "type": "string",
            "description": "ジオコーダーのバージョン（パッケージ版）",
            "example": "0.1.1"
          },
          "abr_data_date": {
            "type": ["string", "null"],
            "description": "ジオコーディングに用いたABRデータの整備基準日（YYYY-MM-DD）。取得できない場合はnull",
            "example": "2026-06-01"
          },
          "candidates": {
            "type": "array",
            "description": "マッチした候補一覧。0件ならマッチなし、2件以上なら判別不能で複数返却",
            "items": {
              "$ref": "#/components/schemas/GeocodeCandidate"
            }
          },
          "truncated": {
            "type": "boolean",
            "description": "候補が内部上限に達して途中で打ち切られた場合true。trueのときはより具体的なクエリでの再検索を推奨"
          },
          "attribution": {
            "type": "string",
            "description": "データの出典表示"
          },
          "usage_policy": {
            "type": "string",
            "description": "本APIの利用条件。地図表示には全国Q地図の埋め込みを使用し、データ保持時はQ地図URLを保持・提示すること"
          },
          "links": {
            "type": "object",
            "description": "全国Q地図の関連リンク",
            "properties": {
              "qchizu_top": {
                "type": "string",
                "format": "uri",
                "description": "全国Q地図トップページURL"
              },
              "qchizu_maps": {
                "type": "string",
                "format": "uri",
                "description": "全国Q地図の地図ページURL"
              },
              "documentation": {
                "type": "string",
                "format": "uri",
                "description": "本APIのOpenAPI仕様書URL"
              }
            }
          }
        }
      },
      "GeocodeCandidate": {
        "type": "object",
        "required": ["matched", "match_level"],
        "description": "ジオコーディング結果の単一候補（version=2）",
        "properties": {
          "matched": {
            "type": "string",
            "description": "マッチした住所・所在地（ABRでヒットした住所レコードの表記）"
          },
          "geocoding_matched": {
            "type": ["string", "null"],
            "description": "位置情報の粒度に対応するマッチ地名。location_levelがmatch_levelより浅い（親階層へフォールバック）場合はlocation_levelまでの地名。通常マッチではmatchedと同じ"
          },
          "furigana": {
            "type": ["string", "null"],
            "description": "マッチした住所・所在地のフリガナ（カタカナ）"
          },
          "trailing": {
            "type": "string",
            "description": "マッチした住所・所在地に続く文字列（建物名・部屋番号・地先 等）"
          },
          "unused": {
            "type": "string",
            "description": "マッチに利用されなかった部分（クエリにあるがABRにない文字列）"
          },
          "supplemented": {
            "type": "string",
            "description": "マッチ成立のためにクエリへ補った文字列（クエリには無いがABRにある要素。unusedと対の概念）"
          },
          "match_level": {
            "type": "string",
            "description": "入力をどこまでマッチできたか（pref: 都道府県, city: 郡/市区町村, oaza-machi: 大字・町, chome: 丁目, doro: 道路（京都通り名等）, koaza: 小字, chiban: 地番, gaiku: 街区符号, jukyo: 住居番号）",
            "enum": ["none", "pref", "city", "oaza-machi", "chome", "doro", "koaza", "chiban", "gaiku", "jukyo"]
          },
          "location_level": {
            "type": ["string", "null"],
            "description": "経緯度（position）が取得された粒度。match_levelに位置情報がない場合は親レベルへフォールバック。positionがnullのときはnull",
            "enum": ["none", "pref", "city", "oaza-machi", "chome", "doro", "koaza", "chiban", "gaiku", "jukyo", null]
          },
          "position": {
            "oneOf": [
              { "$ref": "#/components/schemas/Position" },
              { "type": "null" }
            ],
            "description": "位置情報。該当データがない場合はnull"
          },
          "pref_code": {
            "type": ["string", "null"],
            "description": "都道府県コード（2桁）"
          },
          "city_code": {
            "type": ["string", "null"],
            "description": "市区町村コード（5桁）"
          },
          "machi_aza_id": {
            "type": ["string", "null"],
            "description": "町字ID（ABR由来）"
          },
          "has_parcel_data": {
            "type": ["boolean", "null"],
            "description": "当該町字についてABRに地番レコードが存在するか（true=存在, false=未整備, null=未確定/未判定）"
          },
          "has_rsdt_data": {
            "type": ["boolean", "null"],
            "description": "当該町字についてABRに住居表示レコードが存在するか（true/false/nullの意味はhas_parcel_dataと同様）"
          },
          "parcel_id": {
            "type": ["string", "null"],
            "description": "地番ID（地番マッチ時）"
          },
          "blk_id": {
            "type": ["string", "null"],
            "description": "街区ID（住居表示マッチ時）"
          },
          "rsdt_id": {
            "type": ["string", "null"],
            "description": "住居ID（住居表示マッチ時）"
          },
          "address_components": {
            "oneOf": [
              { "$ref": "#/components/schemas/AddressComponents" },
              { "type": "null" }
            ],
            "description": "住所の行政階層別分解。マッチレベルに応じて各フィールドが埋まる"
          },
          "links": {
            "oneOf": [
              { "$ref": "#/components/schemas/CandidateLinks" },
              { "type": "null" }
            ],
            "description": "全国Q地図リンク。位置情報がある場合のみ設定される"
          }
        }
      },
      "Position": {
        "type": "object",
        "required": ["lat", "lon"],
        "properties": {
          "lat": {
            "type": "number",
            "description": "緯度（WGS84、度）"
          },
          "lon": {
            "type": "number",
            "description": "経度（WGS84、度）"
          }
        }
      },
      "AddressComponents": {
        "type": "object",
        "description": "matched文字列を行政階層別に分解したもの。各レベルに値がない場合はnull",
        "properties": {
          "pref": {
            "type": ["string", "null"],
            "description": "都道府県名"
          },
          "county": {
            "type": ["string", "null"],
            "description": "郡名（あれば）"
          },
          "city": {
            "type": ["string", "null"],
            "description": "市区町村名（郡を除く）"
          },
          "ward": {
            "type": ["string", "null"],
            "description": "区名（政令指定都市の場合）"
          },
          "oaza_cho": {
            "type": ["string", "null"],
            "description": "大字・町名"
          },
          "chome": {
            "type": ["string", "null"],
            "description": "丁目（あれば）"
          },
          "koaza": {
            "type": ["string", "null"],
            "description": "小字（あれば）"
          },
          "chiban": {
            "type": ["string", "null"],
            "description": "地番（フォーマット済み文字列。例: 647番2 または 647-2）"
          },
          "gaiku": {
            "type": ["string", "null"],
            "description": "街区符号の数値部分（『番』を含まない。例: 7）"
          },
          "jukyo": {
            "type": ["string", "null"],
            "description": "住居番号の数値部分（『号』を含まない。例: 5）"
          }
        }
      },
      "CandidateLinks": {
        "type": "object",
        "required": ["qchizu_map", "qchizu_embed"],
        "properties": {
          "qchizu_map": {
            "type": "string",
            "format": "uri",
            "description": "全国Q地図で当該地点を表示するURL"
          },
          "qchizu_embed": {
            "type": "string",
            "format": "uri",
            "description": "全国Q地図の埋め込み用URL（iframeのsrcに指定可）"
          }
        }
      },
      "ElevationResponse": {
        "type": "object",
        "required": ["result", "query", "links", "attribution", "usage_policy", "links_global"],
        "properties": {
          "result": {
            "type": "object",
            "required": ["elevation", "source"],
            "description": "標高取得結果",
            "properties": {
              "elevation": {
                "type": ["number", "null"],
                "description": "標高値（メートル単位）。DEM10Bは1m単位（整数）、その他は0.1m単位（小数第1位）で返却。標高データが存在しない地点（日本国外や海上等）の場合はnull"
              },
              "source": {
                "oneOf": [
                  { "$ref": "#/components/schemas/ElevationSource" },
                  { "type": "null" }
                ],
                "description": "使用した標高データソースの情報。標高データが存在しない場合はnull"
              }
            }
          },
          "query": {
            "type": "object",
            "required": ["lat", "lon"],
            "description": "入力パラメータのエコーバック",
            "properties": {
              "lat": {
                "type": "number",
                "description": "入力した緯度"
              },
              "lon": {
                "type": "number",
                "description": "入力した経度"
              }
            }
          },
          "links": {
            "type": "object",
            "description": "全国Q地図で当該地点の地形を表示するURL。淡色地図をベースに赤色立体地図（合成）と等高線を重ねた表示。回答にはqchizu_mapリンクを必ず含めてください",
            "properties": {
              "qchizu_map": {
                "type": "string",
                "format": "uri",
                "description": "全国Q地図で当該地点の地形を表示するURL（淡色地図＋赤色立体地図＋等高線）。ブラウザで開くと地形表示の地図が表示される"
              },
              "qchizu_embed": {
                "type": "string",
                "format": "uri",
                "description": "全国Q地図の地形表示埋め込み用URL。iframeのsrcに指定して地形表示の地図を埋め込める"
              }
            }
          },
          "attribution": {
            "type": "string",
            "description": "データの出典表示"
          },
          "usage_policy": {
            "type": "string",
            "description": "本APIの利用条件。地図表示には全国Q地図の埋め込みを使用し、データ保持時はQ地図URLを保持・提示すること"
          },
          "links_global": {
            "type": "object",
            "description": "全国Q地図の関連リンク",
            "properties": {
              "qchizu_top": {
                "type": "string",
                "format": "uri",
                "description": "全国Q地図トップページURL"
              },
              "qchizu_maps": {
                "type": "string",
                "format": "uri",
                "description": "全国Q地図の地図ページURL"
              },
              "documentation": {
                "type": "string",
                "format": "uri",
                "description": "本APIのOpenAPI仕様書URL"
              }
            }
          }
        }
      },
      "ElevationSource": {
        "type": "object",
        "required": ["name", "description", "zoom", "tile_size", "is_jgd2024", "attribution"],
        "description": "標高データソース情報",
        "properties": {
          "name": {
            "type": "string",
            "description": "DEMソース名",
            "enum": ["DEM1A", "DEM5A", "DEM5B", "DEM5C", "DEM10B"]
          },
          "description": {
            "type": "string",
            "description": "DEMソースの説明"
          },
          "zoom": {
            "type": "integer",
            "description": "使用したズームレベル（解像度の指標。値が大きいほど高解像度）"
          },
          "tile_size": {
            "type": "integer",
            "description": "タイルのピクセルサイズ（256または512）",
            "enum": [256, 512]
          },
          "is_jgd2024": {
            "type": "boolean",
            "description": "JGD2024（日本測地系2024）準拠の標高値かどうか。trueの場合はEPSG:105604（JGD2024準拠楕円体高）、falseの場合はEPSG:6695（日本測地系2011の標高）"
          },
          "attribution": {
            "type": "string",
            "description": "データの出典表示"
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": {
            "type": "string",
            "description": "エラーメッセージ"
          }
        }
      }
    }
  }
}