本文へスキップ

APIドキュメント

sDB API の認証、エンドポイント、リクエスト、レスポンス仕様です。

API ドキュメント

この文書は、sDB API を利用するために必要な認証、エンドポイント、リクエスト、レスポンス仕様を説明します。

Base URL

sDB API の Base URL は次の値です。

https://sdb.api.takumi-tokunaga.com

認証

/v1/* の API には API キーが必要です。リクエスト時に次のヘッダーを付与してください。

X-API-Key: $SDB_API_KEY
Accept: application/json

JSON を送信する POST リクエストでは、次のヘッダーも指定してください。

Content-Type: application/json

API キーは tkp_ で始まる 68 文字の文字列です。未発行の場合は、ポートフォリオの Contact ページから取得導線へ進んでください。

共通仕様

  • 文字コードは UTF-8 です。
  • レスポンスは JSON です。
  • ID には publicId を使用します。publicId は sDB が生成する公開用 ID であり、文部科学省の公式 ID ではありません。
  • {publicId} を含むエンドポイントでは、直前の検索や一覧レスポンスで返された publicId を指定します。
  • limit と offset によるページングを使用します。
  • prefectureCode は JP-13 のような都道府県コードです。

代表的なエラー:

{
  "error": "API_KEY_INVALID",
  "message": "api key is invalid"
}

HTTP ステータスの目安:

  • 400: クエリパラメータやリクエスト本文が不正
  • 401: API キーが未指定または無効
  • 402: 日次クレジット不足
  • 403: API キーが失効済み、またはアクセス不可
  • 404: 指定した publicId が存在しない
  • 500: サーバー内部エラー

Institutions

GET /v1/institutions

教育機関を検索します。

Query parameters:

  • q: 検索文字列
  • type: university, graduate_school, junior_college, technical_college, technical_college_advanced, high_school, vocational_school
  • prefectureCode: JP-13 などの都道府県コード
  • limit: 取得件数
  • offset: ページング開始位置

Request:

curl "https://sdb.api.takumi-tokunaga.com/v1/institutions?q=ritsumeikan&type=university&prefectureCode=JP-26&limit=10" \
  -H "X-API-Key: $SDB_API_KEY" \
  -H "Accept: application/json"

Response:

{
  "items": [
    {
      "publicId": "Qh1rOPTq",
      "name": "Ritsumeikan University",
      "displayName": "立命館大学",
      "institutionType": "university",
      "prefectureCode": "JP-26"
    }
  ],
  "total": 1,
  "limit": 10,
  "offset": 0
}

GET /v1/institutions/{publicId}

教育機関の詳細を取得します。{publicId} には GET /v1/institutions のレスポンスで返された publicId を指定します。

curl "https://sdb.api.takumi-tokunaga.com/v1/institutions/Qh1rOPTq" \
  -H "X-API-Key: $SDB_API_KEY" \
  -H "Accept: application/json"

GET /v1/institutions/{publicId}/faculties

教育機関に紐づく学部・研究科を取得します。

curl "https://sdb.api.takumi-tokunaga.com/v1/institutions/Qh1rOPTq/faculties?limit=20" \
  -H "X-API-Key: $SDB_API_KEY" \
  -H "Accept: application/json"

Response:

{
  "items": [
    {
      "publicId": "o4xNXqd4",
      "name": "国際関係学部",
      "displayName": "国際関係学部",
      "academicField": "social_sciences"
    }
  ],
  "total": 16,
  "limit": 20,
  "offset": 0
}

Faculties

GET /v1/faculties/{publicId}/departments

学部・研究科に紐づく学科を取得します。{publicId} には GET /v1/institutions/{publicId}/faculties のレスポンスで返された publicId を指定します。

curl "https://sdb.api.takumi-tokunaga.com/v1/faculties/o4xNXqd4/departments?limit=20" \
  -H "X-API-Key: $SDB_API_KEY" \
  -H "Accept: application/json"

Response:

{
  "items": [
    {
      "publicId": "wcdVaYOl",
      "name": "アメリカン大学・立命館大学国際連携学科",
      "displayName": "アメリカン大学・立命館大学国際連携学科",
      "academicField": "social_sciences",
      "academicTrack": "humanities"
    }
  ],
  "total": 2,
  "limit": 20,
  "offset": 0
}

Suggest

GET /v1/suggest

教育機関名の軽量サジェストを取得します。autocomplete 向けの endpoint で、GET /v1/institutions の total-count query は実行しません。

Query parameters:

  • q: 検索文字列
  • type: 学校種別フィルタ
  • prefectureCode: 都道府県フィルタ
  • limit: 取得件数
curl "https://sdb.api.takumi-tokunaga.com/v1/suggest?q=tokyo&type=university&prefectureCode=JP-13&limit=10" \
  -H "X-API-Key: $SDB_API_KEY" \
  -H "Accept: application/json"

Selection Events

POST /v1/selections

利用者が選択した教育機関、学部、学科を記録します。検索品質や候補順位の改善に使う任意イベントです。検索結果の取得には必須ではありません。

Request:

curl "https://sdb.api.takumi-tokunaga.com/v1/selections" \
  -X POST \
  -H "X-API-Key: $SDB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"type":"institution","publicId":"Qh1rOPTq"}'

Body:

{
  "type": "institution",
  "publicId": "Qh1rOPTq"
}

type は institution, faculty, department のいずれかです。publicId には選択された対象の publicId を指定します。

出典・加工内容・免責

API レスポンスには、文部科学省公開資料を加工したデータが含まれる場合があります。API 利用者がレスポンス内容を外部に表示、保存、再配布、またはサービス内で利用する場合は、出典、加工内容、MEXT 規約リンク、免責を表示してください。

  • 出典: 文部科学省公開資料を加工して作成
  • 加工内容: 取得した公開資料を正規化し、教育機関、学部・研究科、学科、検索語、都道府県コードなどの検索用データへ変換
  • MEXT 利用規約: https://www.mext.go.jp/b_menu/1351168.htm
  • MEXT 利用規約別記: https://www.mext.go.jp/b_menu/1366610.htm
  • 免責: sDB は文部科学省の公式サービスではなく、データの完全性、正確性、最新性を保証しません。