APIについて


松江G空間ミュージアムでは デジタルアーカイブ化された歴史資料の情報を閲覧することのできる Web API を提供します。

Web API には以下の種類があります。


名称 説明 エンドポイントURL HTTPメソッド
資料検索API 検索条件に合致する資料データを取得するAPIです http://g-museum.matsu-reki.jp/reki/api/v1/archives GET
資料詳細API 指定したIDの資料データを取得するAPIです http://g-museum.matsu-reki.jp/reki/api/v1/archives/:id GET
資料関連API 指定したIDの資料に関連する資料を取得するAPIです http://g-museum.matsu-reki.jp/reki/api/v1/archives/:id/chart GET
資料近隣API 指定したIDの資料と位置情報が近い資料データを取得するAPIです http://g-museum.matsu-reki.jp/reki/api/v1/archives/:id/near GET
タグ検索API 検索条件に合致するタグを取得するAPIです http://g-museum.matsu-reki.jp/reki/api/v1/tags GET

リクエスト


共通仕様

  • プロトコル

    HTTP

  • 文字コード

    UTF-8

  • フォーマット

    JSON

  • 日時のフォーマット

    日付・日時のデータを扱う場合、以下のフォーマットの文字列で指定する必要があります。


    データ型 フォーマット 説明
    日付 YYYY-MM-DD

    以下の形式の入力を受け付けます。

    • 2016-1-1
    • 2016-01-01
    日時 YYYY-MM-DDTHH:MM:SSZ

    「T」は固定値です。

    「Z」は省略可能な固定値です。

    「Z」を省略した場合は、日本時間(JST)として扱います。

    「Z」を指定した場合は、UTCとして扱います。

    「T」以降を省略した場合は、JSTとして扱います。

    以下の形式の入力を受け付けます。

    • 2016-1-1T0:0:0Z -> UST 2016/1/1 00:00:00
    • 2016-01-01T00:00:00 -> JST 2016/1/1 00:00:00
    • 2016-1-1 -> JST 2016/1/1 00:00:00

リクエストパラメータ

リクエストではQueryStringで以下のパラメータを指定できます。


パラメータ 説明
query 検索条件(資料検索API、タグ検索APIのみ)
sort ソートキー(複数条件は指定できません)
order ソート順(asc,desc)
per_page 1リクエストで取得できる資料件数。最大100件までです。
page ページ番号

検索条件

リクエストパラメータ「query」の構文について説明します。

query は資料検索API、タグ検索APIでのみ有効です。

キーワード検索

指定したキーワードを含む資料を取得します。

例:いずれかのフィールドに「不味公」が含まれるデータを検索する場合

/api/v1/archives?query=不味公

フィールド指定検索

指定したフィールドがキーワードに部分一致するデータを取得します。

構文:

(フィールド名):(キーワード)

※ フィールドに指定可能な文字列はAPIによって違います。

例:名称に「松江城」を含む資料を検索する場合

/api/v1/archives?query=name:松江城

範囲検索

指定したフィールドが演算子・キーワードの範囲にあるデータを取得します。

構文:

(フィールド名):(演算子)(キーワード)

演算子:

演算子 説明
> 指定した値より大きいデータを取得します。
< 指定した値より小さいデータを取得します。
>= 指定した値以上のデータを取得します。
<= 指定した値以下のデータを取得します。

例:年代が「1980年以降」の資料を検索する場合

/api/v1/archives?query=created_begon_on:>=1980-1-1

タグ検索

指定したタグを持つ資料を取得します。タグは完全一致するタグのみを対象とします。

※ 資料検索APIのみ利用可能です。

構文:

tag:(キーワード)

例:「松江城」タグの設定された資料を検索する場合

/api/v1/archives?query=tag:松江城

否定

指定した検索条件に合致しないデータを取得します。

構文:

-(キーワード)
-(フィールド名):(キーワード)
-tag:(キーワード)

例:タグ「松江城」を含まない資料を検索する場合

/api/v1/archives?query=-tag:松江城

AND検索

検索条件を複数指定する場合は、半角空白で条件を連結することで、各検索条件でAND検索します。

例:「不味公」を含まず、作成日が「1800年」以降の資料を検索する場合

/api/v1/archives?query=-不味公 created_begin_on:>=1800-1-1

↑ページトップに戻る


レスポンス


ステータスコード

HTTPのステータスコードとレスポンスボディのJSON によって「成功」「失敗」を通知します。

API が返すレスポンスコードを以下に示します。

ステータスコード 説明
200 成功。レスポンスボディ内にAPI毎に設定されたデータを格納します。
400 リクエストが不正。必須パラメータがない、パラメータの形式が不正、パラメータの値が範囲外など。
500 サーバ内部エラー

JSON

レスポンスのJSONはIMI共通語彙の仕様を参考にしたデータ構造になってます。

IMI共通語彙の仕様については以下のURLを参照してください。

レスポンスのJSONは以下の内容になります。

{
  # 各種データ
  data:[],

  # IMI 共通語彙の仕様を記載したページのURLです。
  namespace:{
    ic: http://imi.go.jp/ns/core/2,
    mr: http://g-museum.matsu-reki.jp/docs/imi/
  },

  # データのページネーション情報(資料検索、タグ検索APIのみ)
  pagination:{
    count       : 20,  # データ数
    current_page: 1,   # ページ番号
    per_page    : 20,  # 1ページ当たりのデータ数
    total_count : 64,  # データ総数
    total_page  : 4,   # ページ総数
  }
}

↑ページトップに戻る

API詳細


各APIの詳細説明は以下のリンクを参照してください。

↑ページトップに戻る