JBIF:地球規模生物多様性 情報機構日本ノード

このAPIは、GBIF分布記録ストア(Occurrence Store)を対象とします。GBIF分布記録ストアは、分布記録データを処理し、ウェブサービスおよびダウンロードファイルを介したデータ提供を行います。その他、GBIFには、空間情報を提供する地図APIもあります。

プログラム内ではJavaウェブサービスクライエントを用いて、HTTPベースREST対応ウェブサービスを提供しています。APIのコードを書く人の中には、関心のある方もいると思われます。occurrence-ws-clientプロジェクトのページに詳細があります。

・各機能メニュー
分布記録(occurrence)  検索  分布データのダウンロード  分布記録メトリクス  分布記録インベントリ  クエリ・パラメータの解説  分布記録データのダウンロードに使用できる演算子  分布記録データのダウンロードに関する制限

分布記録(occurrence)

このAPIには、単一の分布記録データに関連する機能があります。

リソースURL メソッド レスポンス 説明
/occurrence/{key} GET Occurrence 単一の解釈された分布データに関する詳細を取得
/occurrence/{key}/fragment GET Occurrence 単一の分布データフラグメントを未加工(raw)形式(mxl又はjson)にて取得
/occurrence/{key}/verbatim GET VerbatimOccurrence 報告された分布データに対し解釈を行わず、そのまま取得

検索

このAPIでは、GBIFがインデクス付けを行った分布データの検索が行えます。検索フィルタを使って全結果を表示するためには、各ページに対してリクエストを出さなければなりません。一ページに表示可能な件数は、最大で300件に制限されています。技術的な理由により、一クエリに対し、結果の上限は、200,000件となっています。オフセット・リミットが200,000を超える場合、エラーと表示されます。200,000件を超えるデータを取得したい場合には、非同期のダウンロードサービスを使用してください。

リソースURL メソッド レスポンス 説明 ページング パラメータ
/occurrence/search GET Occurrence 全分布データに対して、フル検索を実施。結果は、関連性の高い順に表示される。 true datasetKey, year, month, eventDate, lastInterpreted, decimalLatitude, decimalLongitude, country, continent, publishingCountry, elevation, depth, institutionCode, collectionCode, catalogNumber, recordedBy, recordNumber, basisOfRecord, taxonKey, scientificName, hasCoordinate, geometry, hasGeospatialIssue, issue, mediaType
/occurrence/search/catalogNumber GET Occurrence 該当するカタログ番号を返す検索。結果は、関連性の高い順に表示される。 false q, limit
/occurrence/search/collectionCode GET Occurrence 該当するコレクション・コードを返す検索。結果は、関連性の高い順に表示される。 false q, limit
/occurrence/search/recordedBy GET Occurrence 該当するコレクション名を返す検索。結果は、関連性の高い順に表示される。 false q, limit
/occurrence/search/institutionCode GET Occurrence 該当する研究機関コードを返す検索。結果は、関連性の高い順に表示される。 false q, limit

分布データのダウンロード

このAPIでは、分布データのダウンロードおよびダウンロードファイルに関する情報を取得することができます。

分布データのダウンロードファイルは、非同期的に生成されます。ユーザからダウンロードのリクエストがあった場合、処理終了後に、作成されたファイルのリンクを記したEメールが送られます。

プログラム内ではJavaウェブサービスクライエントを用いて、HTTPベースREST対応ウェブサービスを提供しています。APIのコードを書く人の中には、関心のある方もいると思われます。occurrence-download-ws-clientプロジェクトのページに詳細があります。

リソースURL メソッド レスポンス 説明 認証 ページング
/occurrence/download/request POST Download key ダウンロードファイル作成プロセスを開始。本機能で使用可能なリクエストについては、 predicatesのセクションを参照のこと。また、ユーザ一人当たりの本機能の利用制限については、limits のセクションを参照のこと。 true false
/occurrence/download/request/{key} GET Download file 入手可能なダウンロードファイルを取得。 false false
/occurrence/download/request/{key} DELETE ダウンロードプロセスを中止。 true false
/occurrence/download GET Download Page 全ダウンロードファイルを表示。この操作は、ADMIN権限を有する者のみ実行可能。 true true
/occurrence/download/{key} GET Download 分布ダウンロードファイルのメタデータを一意キーにより取得 false false
/occurrence/download/{key} PUT 既存の分布ダウンロードファイルの状態を更新。この操作は、ADMIN権限を有する者のみ実行可能。 true false
/occurrence/download/{key} POST 分布ダウンロードファイルのメタデータを作成。この操作は、ADMIN権限を有する者のみ実行可能。 true false
/occurrence/download/{key}/datasets GET Datasets 分布ダウンロードファイルの全データセットを表示。 false false
/occurrence/download/user/{user} GET Download Page ユーザが作成したダウンロードを表示。他のユーザのダウンロードが表示できるのは、ADMIN権限を有する者のみ。 true true
/occurrence/download/dataset/{datasetKey} GET Downloads list データセットのダウンロード状況を表示 true true

分布記録メトリクス

このAPIは、分布データに関するさまざまカウントやメトリクスを表示することができます。現在サポートされているカウントの種類は、スキーマ毎に表示されます。詳細は、以下を参照のこと。

リソースURL メソッド レスポンス 説明 パラメータ
/occurrence/count GET Count 事前に定義したディメンションのセットに対して分布記録カウントを返す。サポートしているディメンションについては、/occurrence/count/schema に示す。カナダにおける地理参照観察レコードのカウント数を表示する場合の例: /occurrence/count?country=CA&isGeoreferenced=true&basisOfRecord=OBSERVATION.
/occurrence/count/schema GET Count 本機能がサポートするメトリクスを表示

分布記録インベントリ

このAPIでは、指定した分布特性に対して、各項目毎の分布記録件数を表示します。現在サポートしている特性の範囲は限られています。それぞれの特性によって、呼び出すサービスが異なります。

リソースURL メソッド レスポンス 説明 パラメータ
/occurrence/counts/basisOfRecord GET Counts レコード根拠毎に分布記録件数を表示
/occurrence/counts/year GET Counts 年毎に分布記録件数を表示 year
/occurrence/counts/datasets GET Counts 指定したタクソン又は国を含むデータセットについて、分布記録件数を表示 country, taxonKey
/occurrence/counts/countries GET Counts 指定の国が公開したデータの対象となっている全ての国における分布記録件数を表示 publishingCountry
/occurrence/counts/publishingCountry GET Counts 指定の国に関するデータを公開している全ての国に関する分布記録件数を表示 country

クエリ・パラメータの解説

上記の分布記録APIには、以下のパラメータを使うことができます。

パラメータ 説明
basisOfRecord レコード根拠(basis of record)。詳細は、BasisOfRecord enumを参照のこと。
catalogNumber 物理コレクション又はディジタルデータセット内において当該レコードに対して割り当てられた任意形式の識別子。一意ではない場合であっても、研究機関とコレクション・コードとの組合せにより、相当程度一意性が高いと考えられる。
collectionCode 研究機関内において、物理コレクション又はディジタルデータセットを一意に特定するために割り当てられた任意形式の識別子。
continent 大陸。詳細は、Continent enumを参照のこと。
country 分布が記録された国を表す2文字の国コード(ISO 3166-1による)
datasetKey 分布記録データセットキー(UUID)
decimalLatitude WGS84系により十進法で表示した緯度(-90~90の範囲)。range queriesをサポートする。
decimalLongitude WGS84系により十進法で表示した経度(-180~180の範囲)。range queriesをサポートする。
depth 海抜高度に対して、相対的な深さをメートルで示したもの。例えば、「特定の高度にある湖面から10メートル下」のように表示する。range queriesをサポートする。
elevation メートル表示の海抜高度。range queriesをサポートする。
establishmentMeans 種の定着方法。詳細は、EstablishmentMeans enumを参照のこと。
eventDate ISO8601形式(yyyy、yyyy-MM、yyyy-MM-dd又はMM-dd)で表示した分布記録の日付。range queriesをサポートする。
geometry WKT形式で既述したポリゴン内に含まれる分布記録を検索。WKTタイプとしては、POINT、LINESTRING、LINEARRING及びPOLYGONのみ許容する。 例えば、POLYGON ((30.1 10.1, 10 20, 20 40, 40 40, 30.1 10.1))で表す形状の場合、次のようなクエリとなる。 /occurrence/search?geometry=POLYGON((30.1 10.1, 10 20, 20 40, 40 40, 30.1 10.1)).
hasCoordinate 緯度および経度の両方の数値を有する分布記録レコードに制限して、検索を行う。すなわち、hasCoordinate=trueの場合には、座標データを有する分布記録レコードのみを対象とし、hasCoordinate=falseの場合には、座標データがない分布記録レコードが対象となる。
hasGeospatialIssue 空間データに問題がある(と我々のレコード解釈により考えられる)分布記録レコードを抽出又は除外する機能。すなわち、hasGeospatialIssue=trueの場合には、空間データに問題があるレコードのみを返し、hasGeospatialIssue=falseの場合には、空間データに問題がないレコードのみを表示する。このパラメータを含めない場合、空間データの問題がある・なしとは無関係に、レコードを返す。
institutionCode 当該レコードを所有する研究機関を特定するために割り当てられた任意形式の識別子。一意性の保証はない。
issue データ解釈上の問題を示す。詳細は、 OccurrenceIssue enumを参照のこと。
lastInterpreted GBIFにおいて当該レコードが最後に変更された日付をISO8601形式(yyyy、yyyy-MM、yyyy-MM-dd又はMM-dd)で表示したもの。range queriesをサポートする。
limit 戻す結果の最大件数。最高で300であり、これを超える数値は、自動的に300に設定される。
mediaType 分布記録に関連するマルチメディアの種類。詳細は、MediaType enumを参照のこと。
month 1月を1とし、以下順次数字により月を表す変数。range queriesをサポートする。
occurrenceID 分布記録レコードに対して、データ公表機関が定めたグローバル一意識別子
publishingCountry レコードを所有する機関の国を表す2文字の国コード(ISO 3166-1による)
q 単純検索用パラメータであり、このパラメータが取る値は、単語または語句である。
recordedBy 当該分布記録レコードを記録した観察者名
recordNumber フィールドで記録された時点において当該レコードに割り当てた識別子
scientificName GBIFバックボーンタクソノミーで使用する学術名。当該命名法に含まれるタクソン及び異名は、全て検索に含まれる。プログラムの内部では、最初に種照合機能 を呼び出して、taxonKeyを取得する。一意の学術名の場合にのみ、結果が返される。ホモニム(一名法による生物名が多く存在する)では、結果が表示されない。taxonKeyと種照合機能とを直接利用することを検討されたい。
taxonKey GBIFバックボーンタクソノミーで使用するタクソンキー。当該命名法に含まれるタクソン及び異名は、全て検索に含まれるため、 taxonKey=212により鳥類を検索すると(すなわち、 /occurrence/search?taxonKey=212)、種とは無関係に全鳥類が該当する。
typeStatus 検索対象に該当する命名タイプ(タイプの状態、タイプの学術名、出版物)
year 4桁表示の暦年。例えば、year=98と入力すると、AD98年と解釈される。range queriesをサポートする。

分布記録データのダウンロードに使用できる演算子

ダウンロードに使用できる演算子を使って、分布記録レコードのダウンロードを行うクエリ表現を作成することができます。

Java APIの述語を作成することに関心がある方のために、参考として、幾つかのテストケース を用意しています。

下表には、ダウンロードのリクエストを作成するために利用可能な演算子を示しました。ダウンロードのリクエストは、download APIにPOSTします。

演算子 説明 用例
equals 等しいか否かを調べる {
"creator":"userName",
"notification_address": ["userName@gbif.org"],
"predicate":
{
"type":"equals",
"key":"BASIS_OF_RECORD",
"value":"LITERATURE"
}
}
and 論理積(AND) {
"creator":"userName",
"notification_address": ["userName@gbif.org"],
"predicate":
{
"type":"and",
"predicates": [{"type":"equals","key":"HAS_GEOSPATIAL_ISSUE","value":"false"},
{"type":"equals","key":"TAXON_KEY","value":"2440447"}]
}
}
or 論理和(OR) {
"creator":"userName",
"notification_address": ["userName@gbif.org"],
"predicate":
{
"type":"or",
"predicates": [{"type":"equals","key":"HAS_GEOSPATIAL_ISSUE","value":"false"},
{"type":"equals","key":"TAXON_KEY","value":"2440447"}]
}
}
lessThan 未満(<) {
"creator":"userName",
"notification_address": ["userName@gbif.org"],
"predicate":
{
"type":"lessThan",
"key":"YEAR",
"value":"1900"
}
}
lessThanOrEquals 以下(≤) {
"creator":"userName",
"notification_address": ["userName@gbif.org"],
"predicate":
{
"type":"lessThanOrEquals",
"key":"ALTITUDE",
"value":"1000"
}
}
greaterThan よりも大(>) {
"creator":"userName",
"notification_address": ["userName@gbif.org"],
"predicate":
{
"type":"greaterThan",
"key":"YEAR",
"value":"1900"
}
}
greaterThanOrEquals 以上(≥) {
"creator":"userName",
"notification_address": ["userName@gbif.org"],
"predicate":
{
"type":"greaterThanOrEquals",
"key":"ALTITUDE",
"value":"1000"
}
}
in 比較する複数の値を指定 {
"creator":"userName",
"notification_address": ["userName@gbif.org"],
"predicate":
{
"type":"in",
"key":"CATALOG_NUMBER",
"values":["cat1","cat2","cat3"]
}
}
within 座標がPOLYGON内にあるか否かを調べる地理空間演算子 {
"creator":"userName",
"notification_address": ["userName@gbif.org"],
"predicate":
{
"type":"within",
"geometry":"POLYGON((-130.78125 51.179342,
-130.78125 22.593726,-62.578125 22.593726,
-62.578125 51.179342,-130.78125 51.179342))"
}
}
not 否定(NOT) {
"creator":"userName",
"notification_address": ["userName@gbif.org"],
"predicate":
{
"type":"not",
"predicate":
{
"type":"equals",
"key":"CATALOG_NUMBER",
"value":"cat1"
}
}
}
like パターン検索 {
"creator":"userName",
"notification_address": ["userName@gbif.org"],
"predicate":
{
"type":"like",
"key":"CATALOG_NUMBER",
"value":"PAPS5-560%"
}
}

分布記録データのダウンロードに関する制限

分布記録データのダウンロードには、多大なリソースを要することから、GBIFプラットフォームにかかる負荷に応じて、制限を行っています。特定のユーザによるダウンロード・リクエストがリソースを占有するのを避けるため、二つのルールを設定しています。

  • ダウンロード総計が100未満である場合、1ユーザが同時にダウンロードできる数は最大で3とする。
  • ダウンロード総計が1000未満である場合、1ユーザが1回にダウンロードできる数は1のみとする。