GeogrAPIロゴパスコロゴ

はじめに

本書は、GeogrAPI が提供する Web API 群のインターフェース仕様書です。

適用される GeogrAPI のバージョンは本書へのパスで指定したバージョンと適合します。

共通仕様

エンドポイント

  • 認証 API
    /auth/
  • GIS API
    /gis/

通信仕様

基本仕様

項目内容
通信方式https（TLS 1.2）
文字コードUTF-8（BOM 無し）
リクエスト最大サイズ6 MB
リクエスト最大実行時間29秒

HTTP リクエスト

API 呼び出し時の HTTP リクエストに関する共通仕様を以下に示す。

項目仕様
HTTP メソッド詳細は各API仕様の項目を参照。

HTTP レスポンス

API の HTTP レスポンスに関する共通仕様を以下に示す。

共通HTTPステータス: 正常系
HTTPステータス説明
200 OK API へのリクエストが正常行われたことを表します。API 自体の正常終了とは異なるため注意してください。次の状況においてもこのコードを返却します。
・検索結果が存在しない
・排他処理により更新が行えない

正常レスポンス例

{
    "result": {
        "viaNo": 0,
        "sec": 1968.248421,
        "meter": 15789.980532,
        "meterToll": 13047,
        "tollInfo": null
    },
    "status": 200,
    "requestId": "4abbde43-a9b4-41be-a68c-e5cd3f281147",
    "error": null
}
共通HTTPステータス: リクエストエラー
HTTPステータス説明
400 Bad Request利用方法の誤り、パラメータの不備を表す。
401 Unauthorized認証に関するエラーを表す。
404 Not Found指定されたリソース・APIが存在しないことを表す。
429 Too Many Requests短時間での連続アクセスに関わるアクセス上限を超えた。

エラーレスポンス例

{
    "result": "",
    "status": 400,
    "requestId": "350722c9-1e5c-4ebf-95e2-9f884e9ab016",
    "error": {
        "code": "ESC0003",
        "message": "入力に誤りがあります",
        "errorDetails": [
            {
                "type": "SrId",
                "message": "4301,4326で指定してください"
            }
        ]
    }
}
共通HTTPステータス: システムエラー
HTTPステータス説明
500 Internal Server ErrorAPI実行時に予期しないエラーが発生した。
JSON 共通レスポンス
名前型説明
statusIntegerHTTP ステータスコードです。
requestIdstringリクエスト ID です。問い合わせの際に併せてご連絡ください。
resultobject各処理の結果情報です。result の内容は各 API によって変わります。詳細は各 API の仕様書を参照ください。

API 仕様

下表から機能毎の API 仕様書を参照ください。
機能名をクリックすると、記述の例をご確認いただけます。

機能説明
ログインアクセスキーにより認証し、本サービスにログインします。
ジオコーディング住所文字列と座標（経緯度）を変換することができます。
・住所文字列→経緯度
・経緯度→住所文字列
検索キーコードからマスタ主題（コンテンツ）が持つ図形データや属性データ、またユーザー主題で登録した図形データなどを検索することができます。
・マスタ主題（県界、市区町村界、町丁字界）の図形検索ができます。
・マスタ主題（国勢調査）の属性検索ができます。
・ユーザー主題（ポリゴン、ポイント）の図形検索ができます。
目標物検索指定された文字列より目標物の経緯度を求めることができます。
・駅名検索（駅名、路線名で検索）
・IC 名検索（IC 名、有料道路名で検索）
空間検索図形データから図形データのキーコードを検索することができます。
・ポイント → ポリゴン
・ポリゴン → ポイント
・ポリゴン → ポリゴン
・ポイント → ポイント
ユーザー主題管理お客様が保持する店舗情報などの位置情報やエリア情報などを登録して管理することができます。
・主題登録、変更、削除
背景地図配信指定された表示位置、範囲、縮尺などから背景地図のベクトルタイル、ラスタータイルを取得することができます。
経路探索座標や探索オプションを指定して２点間の経路探索を行い、以下の情報を取得することができます。
・経路図形
・移動時間、移動距離、有料道路料金など
商圏作成任意点から指定する条件により、以下の商圏を作成することができます。
・円商圏
・道路距離、運転時間商圏
面積按分指定したポリゴン図形から、その形状の面積の比率を求めることができます。
地図画像出力指定した範囲、縮尺などから印刷用の地図画像を取得することができます。

パラメータ制限

共通で決まっている制限を以下に示します。

パラメータ制限
主題コード、主題種別コード 文字数 1～50 文字
使える文字 [a-z|A-Z|0-9|_]
※大文字、小文字は区別される
主題コードと主題種別コードとの組み合わせで一意
※スペース内のポイント、ポリゴンそれぞれで一意
その他のコード 文字数 1～50 文字
それ以外は各 API にある制限に沿う
名称（住所、キーワードなど） 文字数 1～100 文字
それ以外は各 API にある制限に沿う
コンテンツバージョン 以下より選択
・ "202404" ... 2024 年 4 月版コンテンツ
・ "default" ... 最新版コンテンツを使用
・ 未指定 ... 最新版コンテンツを使用

短時間での連続アクセスに関わるアクセス上限

API リクエスト数が１時間（毎時 0 分 0 秒を基準とします）の間に契約時に取り決めた月間アクセス数の 10% を超過した場合、それ以降のリクエストは該当する１時間の間、エラーとなります。

スロットリングの対象となったリクエストには HTTP ステータス 429（Too Many Requests）を返却します。

マッチングレベルについて

ジオコーディング API 及び、ユーザー主題管理のポイント登録、ポイント変更の API ではレスポンスにマッチングレベル（level）とオールマッチフラグ（allMatch）が返却されます。

マッチングレベル（level）の意味は以下の通りです。

値意味
0アンマッチ
1都道府県
2政令市（注1）・郡
3政令市以外の市（注1）・区・町・村
4大字
5字・丁目
6地番・番地
7地番（枝番まで）・号

（注１）政令市は施行年月によりマッチングレベルが異なります。
・ 1982 年4 月以前に政令市になった市はマッチングレベル２になります。具体的には札幌市、横浜市、川崎市、名古屋市、京都市、大阪市、神戸市、広島市、北九州市、福岡市。
・ 1982 年4 月以後に政令市になった市はマッチングレベル３になります。具体的には仙台市、さいたま市、千葉市、新潟市、静岡市、浜松市、堺市、岡山市、相模原市、熊本市。

オールマッチフラグ（allMatch）はマッチングレベル（level）が 6 もしくは 7 の場合にのみ有意であり、それ以外では常に false となります。マッチングレベル（level）が 6 もしくは 7 の場合の値の意味は以下の通りです。

値意味
true入力住所文字列をすべて使用
falseマッチした辞書データよりも入力住所文字列が長く、そのすべては使用していない