このページは www.gbif.org/developer/summary サイトの和訳版です。
GBIF APIにより、登録、検索、表示などの情報サービスが利用できます。
このAPIは、JSON形式のREST対応APIです。Version1のベースURLは、次のとおりです：
https://api.gbif.org/v1/
このAPIは、以下の部分に分割された、分かりやすい構造になっています。
- 登録（registry）
データセット、機関・団体（データ公開機関など）、ネットワークおよびこれらにアクセスするための手段（技術的方法）に関する情報を作成、編集、更新および検索することができます。登録したコンテンツには、クロールを行い、GBIFデータポータルにインデックス付けが行われますが、共用APIとして他の目的にも利用可能です。 - 種（species）
種及び高次分類群に関する情報を検索、表示できる他、名前の解釈やGBIFポータルで使用している生物種の識別子及び正式分類名を調べることができます。 - 分布記録（occurrence）
GBIFがクロールによりインデックス付けを行った分布情報を表示できる他、ページ単位のリアルタイム検索や、非同期処理により大きなバッチファイルのダウンロードが行えます。 - 地図（map）
GBIFに提供された他のサイトのコンテンツを地図の形で表示します。 - ニュース（news）
GBIFに提供されたコンテンツを用いて出版したさまざまなテーマの論文など有益な情報を流します。 - 利用例
APIを用いてデータを利活用する例を紹介します。
登録、種、分布及び地図の各セクションでは、Java形式のWebサービスクライエントを使用します。詳細については、各セクションの「あらまし」をご覧ください。
また、GBIF APIユーザ用メーリングリストに登録することで、質問を行ったり、APIの情報を入手することができます。登録者には、新バージョンやメンテナンスに伴うシステムの停止などの事前情報が通知されます。
このAPIの活用例があれば、GBIF開発者ブログにゲスト投稿してくださることを歓迎します。
このAPIおよびこの解説文書には、誤りなどがないものと考えていますが、何かお気づきのことがあれば、右側にある「feedback」ボタンを使って報告してください。
操作方法
このAPIで使用する共通の横断的パラメータの詳細を以下に示します。- ページング
ページ処理を含むリクエストには、以下のパラメータを使います。
| パラメータ | 説明 |
|---|---|
| limit | 一ページに表示する結果の数を制御。サービスによっては、デフォルトの最大値を超える数値を入れると、自動的に最大値に置き換わる。適切なデフォルト値を使っているので、このパラメータは、特に変更しなくても可。 |
| offset | 検索結果のオフセット値を指定。limit=20でoffset=20の場合、次のページには結果が20個表示される。 |
- 検索範囲
検索パラメータの中には、分布検索にある「year（年）」パラメータのように、範囲指定が可能なものがあります。範囲は、下限値と上限値とをコンマで連結した単一のパラメータ値で指定するのが一般的です。
例：http://api.gbif.org/v1//occurrence/search?year=1800,1899
認証
POST、PUT及びDELETEの各リクエストには、認証が必要です。GBIF APIでは、既に作成してあるGBIFユーザアカウントに基づいたHTTP Basic認証を用いています。
クエリフィルタをfilter.jsonという名前のJSONファイルとし、curlコマンドにより新規にダウンロードを行う場合は、次のように設定します。
$ curl -i --user yourUserName:yourPassword -H "Content-Type: application/json" -H "Accept: application/json" -X POST -d @filter.json http://api.gbif.org/v1/occurrence/download/request
列挙型
GBIF APIは、多くの箇所で、列挙型、すなわち特定のトピックに関する限定的用語を利用しています。このような変数の使い方は、大概ISOやTDWGなど既存の規格に基づいたものとなっています。列挙型は、GBIFのJava APIに実装されていますが、現行バージョンでは、JSONウェブサービスにより、更にダイナミックにアクセスすることが可能です。
| リソースURL | メソッド | レスポンス | 説明 | 認証 |
|---|---|---|---|---|
| /enumeration/basic | GET | Enumeration List | 該当する列挙型を全て表示 | false |
| /enumeration/basic/{ENUMERATION} | GET | Enumeration values | 特定の列挙型に対応する項目を全て表示 | false |
| /enumeration/country | GET | Country List | 国別コード及びタイトルにより全ての国名を表示 | false |
バージョン2に向けての予定
GBIF APIは、現在バージョン1です。以下の点にご留意ください。
- このバージョンは作動が安定しており、次バージョンとの互換性を保つためにRESTリソースやレスポンス・プロパティの削除や名称変更を行うことはありません。ただし、APIに新規リソースを追加することはあります。追加を行う場合には、APIメーリングリストにより通知を行います。
- バグ修正や追加を行う場合には、マイナーバージョンアップとなり、API URLに変更はありません。説明文書およびJavaクライアントコードのみの改定となります。
- 仕様変更の必要が生じた場合、その目的をこのサイトおよびメーリングリストにより通知します。バージョン2にアップする前には、事前通告を十分に行います。
- ベースURLには、適宜バージョン番号を含めます。
APIに関する開発者からのフィードバックは、dev@gbif.orgまでお送りください。