{
  "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を返します。",
        "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: 地番の住所のみ",
            "schema": {
              "type": "string",
              "enum": ["all", "residential", "parcel"],
              "default": "all"
            }
          },
          {
            "name": "fuzzy",
            "in": "query",
            "required": false,
            "description": "ファジーマッチ用ワイルドカード文字（印刷可能な1文字のみ）",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "ジオコーディング結果",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GeocodeResponse"
                },
                "example": {
                  "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"
                  }
                }
              }
            }
          },
          "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" }
                  }
                }
              }
            }
          },
          "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（枝番）"
          }
        }
      },
      "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": "エラーメッセージ"
          }
        }
      }
    }
  }
}