インテグレーションAPI でアイテムをフィルタして取得する

インテグレーションAPI でアイテムを取得する際は、条件を指定してフィルタできます。フィルタの方法は2つあります。

補足

パブリックAPI にはフィルタ機能がありません。アイテムの絞り込みが必要な場合はインテグレーションAPI を使用してください。

方法 1：キーワード検索

GET /items エンドポイントに keyword パラメータを付与すると、アイテムをキーワードで絞り込めます。利用可能なパラメータについては インテグレーションAPIリファレンス を参照してください。

curl

curl -X GET \
  'https://api.cms.reearth.io/api/<workspace>/projects/<project>/models/<model>/items?keyword=Tokyo' \
  --header 'Authorization: Bearer <your_integration_token>'

JavaScript

const TOKEN = "<your_integration_token>";
const url = new URL("https://api.cms.reearth.io/api/<workspace>/projects/<project>/models/<model>/items");
url.searchParams.set("keyword", "Tokyo");

const resp = await fetch(url, {
  headers: {
    Authorization: `Bearer ${TOKEN}`,
    Accept: "application/json",
  },
});
if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
const data = await resp.json();
console.log(data);

トークンをフロントエンドに直接書かないでください

上記サンプルはあくまで動作確認用です。トークンがフロントエンドに露出すると、第三者に悪用されるリスクがあります。本番環境では、バックエンドサーバーでトークンを管理し、そこからインテグレーションAPI を呼び出す構成を推奨します。

方法 2：条件フィルタ（詳細な絞り込み）

より複雑な条件で絞り込む場合は、POST /items/filter エンドポイントに JSON で条件を指定します。

フィルタ条件の構造

条件タイプをキーに、fieldId（フィールドセレクター）・operator・value を指定します。

{
  "filter": {
    "<条件タイプ>": {
      "fieldId": {
        "fieldId": "<field-id>",
        "type": "field"
      },
      "operator": "<演算子>",
      "value": "<値>"
    }
  }
}

文字列フィールドを条件に指定する例

string 条件タイプの contains 演算子を使うと、指定したフィールドの値に特定の文字列が含まれるアイテムだけを絞り込めます。以下は、フィールドの値に「Tokyo」を含むアイテムを取得する例です。

curl -X POST \
  'https://api.cms.reearth.io/api/<workspace>/projects/<project>/models/<model>/items/filter' \
  --header 'Authorization: Bearer <your_integration_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "filter": {
      "string": {
        "fieldId": {
          "fieldId": "<field-id>",
          "type": "field"
        },
        "operator": "contains",
        "value": "Tokyo"
      }
    }
  }'

AND / OR 条件の組み合わせ

複数条件を組み合わせる場合は and / or を使います。

curl -X POST \
  'https://api.cms.reearth.io/api/<workspace>/projects/<project>/models/<model>/items/filter' \
  --header 'Authorization: Bearer <your_integration_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "filter": {
      "and": [
        {
          "basic": {
            "fieldId": { "fieldId": "<field-id-1>", "type": "field" },
            "operator": "equals",
            "value": "high"
          }
        },
        {
          "string": {
            "fieldId": { "fieldId": "<field-id-2>", "type": "field" },
            "operator": "contains",
            "value": "Tokyo"
          }
        }
      ]
    }
  }'

利用可能な条件タイプや演算子の詳細については、インテグレーションAPIリファレンス を参照してください。