JIDS API Document
JIDSのAPIについて、開発者向けにその仕様や使い方を公開しています。こちらに記載されている情報はシステムを外部ツールと連携させて利用したい方向けなので、一般向けではありません。
左側（もしくはスマホなどだと下）にあるメニューからそれぞれのエンドポイントの説明を見ることができます。各エンドポイントの説明は自動で生成しているので変な記述内容になっている場所がありますが何とか読み取ってください。
APIのバージョンについて
現在、APIとしては「v1」と「v2」の双方が存在します。「v2」をお使いください。「v1」は一般管理者以上の方のみを対象として、旧来のデータで検証するためにのみ使用できます。
まもなく、「v1」は使用できなくなるため、v1を使用している方はv2へお乗り換えください。2023年2月28日を持ちまして、v1APIの提供は終了しました。エンドポイントにアクセスすると無効なメッセージが返ってきます。使い方はそこまで変わりませんが、レスポンスが若干異なります。
都道府県コード・エリアコードについて
都道府県コード、エリアコードはそれぞれ「整数」となります。0埋め等を考慮する必要はありません。v1では、エリアコードに「k」などをつけて区別していましたが、廃止しました。
従来のように「k」をつけると何も取得できなくなるのでご注意ください。
認証について
v2より、有効なJIDSアカウント（ロックされていないもの）毎に固有のトークン（一意の文字列）を基に認証を行わないとAPIを実行することができなくなりました。どこかのSNSみたいに有料サービスを展開することはありません。
全てのAPIにおいて、「token」という引数が必須になります。これを取得するためのAPIが「get_token」となるため、そちらを参照してください。
レート制限について
サーバーの負荷軽減のため、1アカウントにつき使用できるAPIの利用可能レートを指定しています。このレートは、通常APIを1回使用するたびに1を消費します。GET、POSTそれぞれでカウントしています。
日本時間毎朝3時にリセットされるようになっており、現在の役職に応じて以下のレートが与えられます。
- 利用者→GET: 25、POST: 10
- 情報提供者→GET: 50、POST: 20
- 一般管理者（情報）→GET: 100、POST: 50
- システムチーム→GET: 500、POST: 100
- 最高管理者→GET: 無制限、POST: 無制限
レートが0になっているにもかかわらず、APIを実行しようとすると、エラーが発生し実行できなくなります。このような場合は、リセットされるまでお待ちください。
何が何でも今すぐレートが必要、という方はその理由を最高管理者まで報告いただければ、必要な回数分追加します。
APIが返却するエラーについて
APIはシステムのエラーやバグ、ユーザーの操作ミスによりエラーを返すことがあります。エラーが発生した場合、「error」というオブジェクトの中にエラー番号とその内容が表示されます。
以下が、現在登録されている（表示される可能性のある）エラー一覧です。
[0] 原因不明のエラーが発生しました。
→システム内部のエラー、あるいは細分化できない一般的なエラーが発生したことを示します。最高管理者に相談してください。
[1] いくつかの引数に致命的な誤りがあります。リクエストを拒否しました。
→引数をお確かめください。例えば、整数しか受け付けない引数に文字列が入力されていたりしています。
[100] 必須となる引数 %1s が不足しています。
→%1sには足りない引数が表示されます。指定された引数で必須の引数がきちんと送信されているかご確認ください。GETなのにPOSTで送信していてもこのような現象が起こることがあります。
[110] %1s番は指定されたエリアに存在しません。
→intersectionに関して、該当する交差点が取得できない場合に表示される予定でしたが、データの持ち方が変わったのでこのエラーは基本的に出てこなくなりました。代わりに、空のオブジェクトが返されるようになっています。
[111] 指定したエリア番号のうち1つ以上が存在しないためデータを返せません。
→areaに関して、該当するエリアが存在しない場合に表示されることがあります。
[121] 検索引数「%1s」に誤りがあります。
→searchに関して、%1sに表示されている引数の書式が誤っています。なお、最低でもこのパラメーターがおかしい、ということであり、ほかのパラメーターもおかしい可能性があります。見直してみてください。
[200] API呼び出しの上限回数を超えています。翌朝3時以降再度アクセスしてください。
→1日のAPI使用可能回数の上限を超えました。リセットされるまでお待ちください。どうしても今すぐ使いたい方はその理由と共に最高管理者にご連絡ください。
[201] このアカウントはロックされています。APIの利用はできません。
→使用しようとしたユーザーはロックされているため、APIを利用することができません。ロックの解除を希望の方は最高管理者に連絡してください。ただし、ロックされているにはそれ相応の理由があります。
[300] アップロードされたファイルの解析に失敗しました。
→送信時にエラーが発生した、元のZipファイルが壊れていたなどでファイルチェックに失敗した場合に表示されます。ZIPファイルが正しい形式になっているか確認したうえで、安定した回線で送信してください。
[301] 何もファイルがアップロードされていません。
→ファイルが送信されてきませんでした。確実に送信している場合は、回線の影響かもしれません。再度送信してみてください。
[302] アップロードされたファイルはZipファイルではありません。拡張子だけを変えても読み込めません。
→アップロードされたZipファイルは有効なZipアーカイブ形式ではありません。よくあるのが、拡張子だけzipにしたけど中身が画像ファイルだったというパターンです。お使いの端末でそのZipファイルがきちんと開けるか確認してみてください。
[303] アップロードされたファイルにパスワードがかけられています。パスワードを外して再度送信してください。
→Zipファイルにはパスワードがかけられますが、そのパスワードをシステムは知らないので中身を閲覧することができません。パスワードをかけている場合は外してください。
[304] ファイルサイズが大きすぎます。最大2GBです。
→システムでは、回線の関係・サーバースペックを考慮して最大2GBまでの送信にのみ対応しています。これを超えるZipファイルは、分割してお送りいただくか画像を小さくするなどしてファイルサイズを減らしてください。
[305] キューの登録に失敗しました
→データは正常に送られてきましたが、正常にキューを保存できなかった場合に表示されます。再度送信してみて、ダメだったら最高管理者にご連絡ください。
[401] ログイン認証に失敗しました。
→ユーザー名とパスワードが不正か、トークンが期限切れあるいは存在しないものとなっています。正しい値を入れてください。
[403] このAPIを使用する権限がありません。
→このAPIを使用するために必要なランクが不足しています。ドキュメントを参考に、適したランクかどうかをチェックしてください。
[404] 指定したAPIは現在存在していません。
→コードが示すとおり、そのようなエンドポイントは存在しません。URLが正しいかご確認ください。
[405] このAPIは%1sによるアクセスのみ対応しています。
→%1sにはメソッドタイプが表示されます。GETなのにPOSTでアクセスしたりすると表示されることがあります。コードはHTTPコードに対応しています。
[500] サーバーエラーが発生しました。しばらく待ってからやり直してください。
→通常表示されることはありません。これが発生した場合は最高管理者にご連絡ください。
[599] システムメンテナンス中です。しばらく待ってからやり直してください。
→システム側で意図的にAPIの提供を中断しているときに表示されます。しばらく待ってから再度アクセスしてみてください。