> ## Documentation Index
> Fetch the complete documentation index at: https://docs.signa.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Data Freshness & Coverage

> Per-office sync schedules and consistency model

Signa ingests trademark data from 10 production offices, with more planned. Each office publishes data on its own schedule. This guide explains what to expect in terms of data freshness and how to check the current state of each source.

## Per-Office Sync Schedule

### Production Offices

| Office       | Code      | Frequency          |
| ------------ | --------- | ------------------ |
| USPTO        | `uspto`   | Daily              |
| INPI France  | `inpi-fr` | Weekly             |
| EUIPO        | `euipo`   | Daily              |
| IP Australia | `ipau`    | Daily              |
| CIPO         | `cipo`    | Weekly             |
| WIPO         | `wipo`    | Weekly per country |
| IPOS         | `ipos`    | Daily              |
| PRV          | `prv`     | Daily              |
| IPI          | `ipi`     | Daily              |
| NIPO         | `nipo`    | Daily              |

<Note>
  Each record carries its own `source_data_date` — that's the authoritative answer to "how current is this trademark?" Use it instead of guessing from the office's sync frequency.
</Note>

### Planned Offices

The following offices are planned for future phases. Connector scaffolds and data source research are in progress.

DPMA (Germany), UKIPO (United Kingdom), BOIP (Benelux), DKPTO (Denmark), PRH (Finland), ISIPO (Iceland), UPRP (Poland), IMPI (Mexico), JPO (Japan), KIPO (South Korea), CNIPA (China), DIP (Thailand), IP Vietnam.

<Note>
  Sync frequencies represent the target schedule for production offices. Actual freshness depends on office uptime and data availability. Use the `source_data_date` field to determine the actual age of any individual record.
</Note>

## Understanding `source_data_date`

Every trademark record carries a `source_data_date` field that indicates when the data was published by the source office -- not when Signa ingested it. This distinction matters:

| Field              | Meaning                                            |
| ------------------ | -------------------------------------------------- |
| `source_data_date` | When the office published this version of the data |
| `updated_at`       | When Signa last wrote to this record               |
| `created_at`       | When Signa first ingested this record              |

For example, a USPTO record with `source_data_date: "2026-03-20"` and `updated_at: "2026-03-22T10:15:00Z"` means the data was part of the March 20 daily file, which Signa processed on March 22.

<CodeGroup>
  ```bash cURL theme={null}
  # Check when a mark was last updated
  curl -s https://api.signa.so/v1/trademarks/tm_abc123 \
    -H "Authorization: Bearer sig_xxx" | jq '{source_data_date, updated_at}'
  ```

  ```typescript TypeScript theme={null}
  const tm = await signa.trademarks.retrieve("tm_abc123");
  console.log(tm.source_data_date); // "2026-03-20"
  console.log(tm.updated_at);       // "2026-03-22T10:15:00Z"
  ```

  ```python Python theme={null}
  tm = client.trademarks.retrieve("tm_abc123")
  print(tm.source_data_date)  # 2026-03-20
  print(tm.updated_at)        # 2026-03-22T10:15:00Z
  ```
</CodeGroup>

## Consistency Model

Signa offers two consistency tiers for trademark reads. The difference matters when you read a record immediately after it was updated.

### Detail endpoints

* **Consistency:** Immediate (strong read-after-write)
* **Endpoints:** `GET /v1/trademarks/{id}` and other single-resource fetches
* Use when you need the absolute current state -- fresh out of an ingestion run, post-update, or post-replay.

### Search endpoints

* **Consistency:** Eventually consistent
* **Lag:** Typically under 30 seconds after a write
* **Endpoints:** `GET` and `POST /v1/trademarks` (list + search)
* In rare cases (search index rebuild, backlog) lag can extend to minutes.

**What this means in practice:**

1. When a trademark is updated, the detail endpoint reflects the change immediately
2. The search endpoint may take up to 30 seconds to reflect the same change
3. Searches followed by detail fetches (the typical pattern) always see consistent data because the detail leg reads from the authoritative store

<CodeGroup>
  ```bash cURL theme={null}
  # Detail endpoint -- always current
  curl -s https://api.signa.so/v1/trademarks/tm_abc123 \
    -H "Authorization: Bearer sig_xxx"

  # Search endpoint -- eventually consistent
  curl -s -X POST https://api.signa.so/v1/trademarks \
    -H "Authorization: Bearer sig_xxx" \
    -H "Content-Type: application/json" \
    -d '{"query": "SIGNA"}'
  ```

  ```typescript TypeScript theme={null}
  // Immediate consistency
  const detail = await signa.trademarks.retrieve("tm_abc123");

  // Eventually consistent
  const results = await signa.trademarks.search({ query: "SIGNA" });
  ```

  ```python Python theme={null}
  # Immediate consistency
  detail = client.trademarks.retrieve("tm_abc123")

  # Eventually consistent
  results = client.trademarks.search(query="SIGNA")
  ```
</CodeGroup>

## Checking Office Status

Use the reference data endpoints to check the current sync status of each office:

<CodeGroup>
  ```bash cURL theme={null}
  # List all offices with their sync status
  curl -s https://api.signa.so/v1/offices \
    -H "Authorization: Bearer sig_xxx"

  # Get a specific office
  curl -s https://api.signa.so/v1/offices/uspto \
    -H "Authorization: Bearer sig_xxx"
  ```

  ```typescript TypeScript theme={null}
  const offices = await signa.offices.list();
  for (const office of offices.data) {
    console.log(office.code, office.last_sync_completed_at, office.record_count);
  }
  ```

  ```python Python theme={null}
  offices = client.reference.list_offices()
  for office in offices.data:
      print(office.code, office.last_sync_completed_at, office.record_count)
  ```
</CodeGroup>

## Finding Recently Updated Records

Filter by `updated_at` to find records that changed within a time window:

<CodeGroup>
  ```bash cURL theme={null}
  # All marks updated in the last 24 hours
  curl -s "https://api.signa.so/v1/trademarks?updated_at_gte=2026-03-23T00:00:00Z&sort=-updated_at" \
    -H "Authorization: Bearer sig_xxx"
  ```

  ```typescript TypeScript theme={null}
  const recent = await signa.trademarks.list({
    updated_at_gte: "2026-03-23T00:00:00Z",
    sort: "-updated_at",
  });
  ```

  ```python Python theme={null}
  recent = client.trademarks.list(
      updated_at_gte="2026-03-23T00:00:00Z",
      sort="-updated_at",
  )
  ```
</CodeGroup>

For fine-grained change history on a specific mark, use [Trademark History](/api-reference/trademarks/trademark-history) and [Trademark Changes](/api-reference/trademarks/trademark-changes).

## Known Limitations

<AccordionGroup>
  <Accordion title="Some offices have delayed publication">
    Certain offices publish data with a built-in delay. For example, some offices only publish weekly gazette updates, meaning a status change on Monday may not appear in Signa's data until the following week's publication.
  </Accordion>

  <Accordion title="Historical data may be incomplete">
    Full sync captures the current state of each record but may not include all historical events. Some offices only provide current snapshots without event history. Signa preserves all events it observes going forward, but events that occurred before the first ingestion may be missing.
  </Accordion>

  <Accordion title="Image availability varies by office">
    Not all offices make mark images available via their data feeds. Some require separate image downloads. Image availability is indicated by the `has_media` field on trademark records.
  </Accordion>

  <Accordion title="Goods and services text language">
    Most offices provide goods/services descriptions in their local language. Signa stores the original text and language code but does not translate. Some offices (EUIPO, WIPO) provide multi-language descriptions.
  </Accordion>
</AccordionGroup>