Filtering items with Integration API

When retrieving items with Integration API, you can filter them by specifying conditions. There are two ways to filter.

Note

Public API has no filtering feature. If you need to narrow down items, use Integration API instead.

Method 1: Keyword search

Adding a keyword parameter to the GET /items endpoint lets you narrow down items by keyword. See Integration API Reference for the available parameters.

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);

Don't hardcode tokens in frontend code

The sample above is for testing purposes only. If the token is exposed in the frontend, a third party could misuse it. In production, we recommend managing the token on a backend server and calling Integration API from there.

Method 2: Condition filters (fine-grained filtering)

For more complex filtering, specify conditions as JSON in a request to the POST /items/filter endpoint.

Filter condition structure

Use a condition type as the key, and specify fieldId (a field selector), operator, and value.

{
  "filter": {
    "<condition-type>": {
      "fieldId": {
        "fieldId": "<field-id>",
        "type": "field"
      },
      "operator": "<operator>",
      "value": "<value>"
    }
  }
}

Example: filtering on a string field

Using the contains operator with the string condition type lets you narrow down items whose specified field contains a given substring. Here’s an example that retrieves items where the field’s value 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"
      }
    }
  }'

Combining AND / OR conditions

To combine multiple conditions, use 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"
          }
        }
      ]
    }
  }'

For details on the available condition types and operators, see Integration API Reference.