# Searching and Filtering

The IntelCenter API supports direct Component ID lookup, structured keyword search, natural-language retrieval, and Geo Manifest traversal.

## Choose the Most Direct Method

1. **Known Component ID:** use `/by-component-id/{component_id}`.
2. **Known record UUID:** use `/{uuid}`.
3. **Exact terms or filters:** use structured search.
4. **Conceptual request:** use Natural Language Search.
5. **Analytical question:** use Domain GenAI.

## Component ID Lookup

```bash
curl --request GET \
  --url "https://api.intelcenter.com/v1/icd/images/by-component-id/123456" \
  --header "Authorization: Bearer YOUR_API_KEY"
```

The number is a placeholder. A direct lookup avoids the ambiguity of treating an identifier as a keyword.

## Keyword Search

Keyword-search performance has been materially improved without changing its public request or response contract.

```bash
curl --request GET \
  --url "https://api.intelcenter.com/v1/icd/videos?search=public%20safety&country=USA&page=1&per_page=10" \
  --header "Authorization: Bearer YOUR_API_KEY"
```

Common parameters:

| Parameter | Purpose |
|---|---|
| `search` | Full-text search term |
| `entity` | Associated entity |
| `country` | Primary country |
| `date_from` | Earliest date, formatted `YYYY-MM-DD` |
| `date_to` | Latest date, formatted `YYYY-MM-DD` |
| `page` | One-based page number |
| `per_page` | Requested page size |
| `sort` | Supported result order |

Support varies by endpoint. The [API Reference](/api) is authoritative.

## Natural Language Search

```bash
curl --request GET \
  --url "https://api.intelcenter.com/v1/icd/nl-search?search=emergency%20response%20and%20public%20safety&source_component=video&top_k=10" \
  --header "Authorization: Bearer YOUR_API_KEY"
```

Natural Language Search returns ranked records. Relevance scores are comparative signals, not probabilities or confidence guarantees.

## Date Ranges

Dates are inclusive and use `YYYY-MM-DD`.

```text
date_from=2026-01-01&date_to=2026-01-31
```

## URL Encoding

Encode spaces and reserved characters in query values. Most HTTP libraries do this when parameters are provided separately.

## Geo Manifest Continuation

Geo Manifest results use deterministic newest-first ordering. Records with the same primary date are ordered by Component ID descending.

Start without a cursor. If the response supplies `next_cursor`, repeat the exact same dataset, component, filters, page size, and format with that cursor.

```bash
curl --request GET \
  --url "https://api.intelcenter.com/v1/icd/videos/geo-manifest?country=USA&per_page=500&format=geojson" \
  --header "Authorization: Bearer YOUR_API_KEY"
```

Do not construct or modify cursor values. They are opaque and bound to the original request context. If a cursor is rejected as invalid or stale, restart the same request without a cursor.