> ## 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

export const officeCount = 10;

Signa syncs trademark data from {officeCount} 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        | `US` | Daily              |
| INPI France  | `FR` | Weekly             |
| EUIPO        | `EM` | Daily              |
| IP Australia | `AU` | Daily              |
| CIPO         | `CA` | Weekly             |
| WIPO         | `WO` | Weekly per country |
| IPOS         | `SG` | Daily              |
| PRV          | `SE` | Daily              |
| IPI          | `CH` | Daily              |
| NIPO         | `NO` | Daily              |

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

### Planned offices

Additional offices are planned and will be onboarded progressively: 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's detail response carries a `data_freshness` object that tells you when the office published the data and when Signa last touched the record:

| Field                             | Meaning                                            |
| --------------------------------- | -------------------------------------------------- |
| `data_freshness.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 synced 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 office's March 20 publication, 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_YOUR_KEY" | jq '{source_data_date: .data_freshness.source_data_date, updated_at}'
  ```

  ```typescript TypeScript theme={null}
  const tm = await signa.trademarks.retrieve("tm_abc123");
  console.log(tm.data_freshness.source_data_date); // "2026-03-20"
  console.log(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, right after a scheduled sync or a correction.

### Search endpoints

* **Consistency:** Eventually consistent
* **Lag:** Typically under 30 seconds after a write
* **Endpoints:** `GET` and `POST /v1/trademarks` (list and search)
* In rare cases, such as right after a large batch of updates, lag can extend to a few 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 endpoint reflects every write immediately, even if search hasn't caught up yet.

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

  # Search endpoint: eventually consistent
  curl -s -X POST https://api.signa.so/v1/trademarks \
    -H "Authorization: Bearer sig_YOUR_KEY" \
    -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" });
  ```
</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_YOUR_KEY"

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

  ```typescript TypeScript theme={null}
  const offices = await signa.references.offices();
  for (const office of offices.data) {
    console.log(office.code, office.last_synced_at, office.total_marks);
  }
  ```
</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
  SINCE=$(date -u -d '-24 hours' '+%Y-%m-%dT%H:%M:%SZ')
  curl -s "https://api.signa.so/v1/trademarks?updated_at_gte=$SINCE&sort=-updated_at" \
    -H "Authorization: Bearer sig_YOUR_KEY"
  ```

  ```typescript TypeScript theme={null}
  const since = new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString();
  const recent = await signa.trademarks.list({
    updated_at_gte: since,
    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">
    A 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 sync may be missing.
  </Accordion>

  <Accordion title="Image availability varies by office">
    Not all offices make mark images available through 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>