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

# Filing Routes & Mark Types

> How trademarks are filed, classified, and how these dimensions affect search and filtering

Every trademark in Signa carries three classification dimensions: how it was filed (filing route), what type of mark it is (mark feature type), and what legal category it belongs to (legal category). Understanding these dimensions is essential for building accurate search queries and interpreting results.

## Filing Routes

The filing route describes the procedural path through which a trademark application was submitted.

| Route                  | Value                | Description                                                                    |
| ---------------------- | -------------------- | ------------------------------------------------------------------------------ |
| **Direct national**    | `direct_national`    | Filed directly at a national office (e.g., USPTO, CIPO)                        |
| **Direct regional**    | `direct_regional`    | Filed directly at a regional office (e.g., EUIPO for the EU, BOIP for Benelux) |
| **Madrid designation** | `madrid_designation` | A country designation under a Madrid Protocol international registration       |
| **Transformation**     | `transformation`     | A national application created from a cancelled Madrid designation             |
| **Divisional**         | `divisional`         | Split from a parent application (e.g., to separate contested classes)          |
| **Unknown**            | `unknown`            | Route could not be determined from source data                                 |

### Scope Kind

Related to filing route, the `scope_kind` field classifies the territorial scope:

| Scope                        | Description                       | Typical Routes                                            |
| ---------------------------- | --------------------------------- | --------------------------------------------------------- |
| `national`                   | Protection in one country         | `direct_national`, `madrid_designation`, `transformation` |
| `regional`                   | Protection across a regional bloc | `direct_regional`                                         |
| `international_registration` | WIPO international register       | `madrid_designation`                                      |

### Filtering by Route

<CodeGroup>
  ```bash cURL theme={null}
  # All direct national filings
  curl -s "https://api.signa.so/v1/trademarks?filing_route=direct_national" \
    -H "Authorization: Bearer sig_xxx"

  # All Madrid marks
  curl -s "https://api.signa.so/v1/trademarks?is_madrid=true" \
    -H "Authorization: Bearer sig_xxx"
  ```

  ```typescript TypeScript theme={null}
  // Direct national filings only
  const national = await signa.trademarks.list({
    filing_route: "direct_national",
  });

  // All Madrid marks
  const madrid = await signa.trademarks.list({
    is_madrid: true,
  });

  // Regional filings (EUIPO, BOIP)
  const regional = await signa.trademarks.list({
    filing_route: "direct_regional",
  });
  ```

  ```python Python theme={null}
  # Direct national filings
  national = client.trademarks.list(filing_route="direct_national")

  # All Madrid marks
  madrid = client.trademarks.list(is_madrid=True)

  # Regional filings
  regional = client.trademarks.list(filing_route="direct_regional")
  ```
</CodeGroup>

Search aggregations include `filing_route` breakdowns:

```json theme={null}
{
  "aggregations": {
    "filing_route": {
      "direct_national": 3800,
      "madrid_designation": 1547,
      "direct_regional": 647
    }
  }
}
```

## Mark Feature Types (16 values)

The mark feature type describes the visual or sensory form of the trademark.

| Type           | Value        | Description                            |
| -------------- | ------------ | -------------------------------------- |
| **Word**       | `word`       | Text only, no stylization              |
| **Figurative** | `figurative` | Logo or design, no text                |
| **Combined**   | `combined`   | Text + design elements together        |
| **3D**         | `three_d`    | Three-dimensional shape                |
| **Color**      | `color`      | A specific color or color combination  |
| **Sound**      | `sound`      | Audio mark (jingle, chime)             |
| **Motion**     | `motion`     | Animated or moving mark                |
| **Hologram**   | `hologram`   | Holographic mark                       |
| **Pattern**    | `pattern`    | Repeating pattern applied to a surface |
| **Position**   | `position`   | Mark defined by its position on goods  |
| **Multimedia** | `multimedia` | Combination of image and sound         |
| **Scent**      | `scent`      | Olfactory mark (extremely rare)        |
| **Taste**      | `taste`      | Gustatory mark (extremely rare)        |
| **Texture**    | `texture`    | Tactile mark                           |
| **Other**      | `other`      | Non-standard type                      |
| **Unknown**    | `unknown`    | Type could not be determined           |

The vast majority of marks are `word`, `figurative`, or `combined`. Non-traditional marks (sound, scent, hologram, etc.) represent a small but growing percentage.

<CodeGroup>
  ```bash cURL theme={null}
  # All figurative marks in the EU
  curl -s "https://api.signa.so/v1/trademarks?mark_feature_type=figurative&jurisdictions=EU" \
    -H "Authorization: Bearer sig_xxx"
  ```

  ```typescript TypeScript theme={null}
  const logos = await signa.trademarks.list({
    mark_feature_type: "figurative",
    jurisdictions: "EU",
  });
  ```

  ```python Python theme={null}
  logos = client.trademarks.list(
      mark_feature_type="figurative",
      jurisdictions="EU",
  )
  ```
</CodeGroup>

### Impact on Search

The mark feature type affects how search works:

* **Word marks** are matched by text similarity (phonetic, visual, conceptual)
* **Figurative marks** may have `mark_text: null` -- they can only be found via design codes (Vienna classification) or owner/class filters
* **Combined marks** are searchable by both text and design codes

## Legal Categories (9 values)

The legal category classifies the legal nature of the trademark right.

| Category                    | Value                     | Description                                                     |
| --------------------------- | ------------------------- | --------------------------------------------------------------- |
| **Standard**                | `standard`                | Ordinary trademark identifying goods/services of one enterprise |
| **Collective**              | `collective`              | Indicates membership in an association                          |
| **Certification**           | `certification`           | Certifies characteristics (quality, origin, materials)          |
| **Collective membership**   | `collective_membership`   | Indicates membership without certifying quality                 |
| **Defensive**               | `defensive`               | Registered to prevent others from using (AU-specific)           |
| **Guarantee**               | `guarantee`               | Guarantees quality standards (some jurisdictions)               |
| **Geographical indication** | `geographical_indication` | Identifies goods originating from a specific place              |
| **Other**                   | `other`                   | Non-standard category                                           |
| **Unknown**                 | `unknown`                 | Category could not be determined                                |

The overwhelming majority of marks are `standard`. Collective and certification marks have special rules around who can use them and how they are enforced.

<CodeGroup>
  ```bash cURL theme={null}
  # All certification marks
  curl -s "https://api.signa.so/v1/trademarks?mark_legal_category=certification" \
    -H "Authorization: Bearer sig_xxx"

  # Geographical indications
  curl -s "https://api.signa.so/v1/trademarks?mark_legal_category=geographical_indication" \
    -H "Authorization: Bearer sig_xxx"
  ```

  ```typescript TypeScript theme={null}
  const certMarks = await signa.trademarks.list({
    mark_legal_category: "certification",
  });
  ```

  ```python Python theme={null}
  cert_marks = client.trademarks.list(
      mark_legal_category="certification"
  )
  ```
</CodeGroup>

## Right Kind (5 values)

Distinct from legal category, `right_kind` classifies the type of IP right:

| Kind                        | Value                     | Description                                     |
| --------------------------- | ------------------------- | ----------------------------------------------- |
| **Trademark**               | `trademark`               | Standard trademark                              |
| **Trade name**              | `trade_name`              | Business name registration                      |
| **Commercial notice**       | `commercial_notice`       | Commercial notice (some Latin American offices) |
| **Geographical indication** | `geographical_indication` | GI registered as a standalone right             |
| **Other**                   | `other`                   | Non-standard right type                         |

Most records are `trademark`. The `right_kind` field exists because some offices register trade names and GIs in the same database as trademarks.

## Combining Dimensions

These classification fields work together for precise filtering. Some common combinations:

| Use Case                            | Filters                                                                      |
| ----------------------------------- | ---------------------------------------------------------------------------- |
| Word marks filed directly in the US | `mark_feature_type=word`, `filing_route=direct_national`, `jurisdictions=US` |
| Madrid designations in the EU       | `filing_route=madrid_designation`, `offices=euipo`                           |
| All certification marks globally    | `mark_legal_category=certification`                                          |
| Figurative marks in Nice Class 25   | `mark_feature_type=figurative`, `nice_classes=25`                            |
| GIs registered in the EU            | `mark_legal_category=geographical_indication`, `jurisdictions=EU`            |

<CodeGroup>
  ```bash cURL theme={null}
  # Word marks filed directly in the US, Nice Class 9
  curl -s "https://api.signa.so/v1/trademarks?\
  mark_feature_type=word&\
  filing_route=direct_national&\
  jurisdictions=US&\
  nice_classes=9" \
    -H "Authorization: Bearer sig_xxx"
  ```

  ```typescript TypeScript theme={null}
  const results = await signa.trademarks.list({
    mark_feature_type: "word",
    filing_route: "direct_national",
    jurisdictions: "US",
    nice_classes: "9",
  });
  ```

  ```python Python theme={null}
  results = client.trademarks.list(
      mark_feature_type="word",
      filing_route="direct_national",
      jurisdictions="US",
      nice_classes="9",
  )
  ```
</CodeGroup>

## Search Aggregations

All three classification dimensions are available as search aggregations:

<CodeGroup>
  ```bash cURL theme={null}
  curl -s -X POST https://api.signa.so/v1/trademarks \
    -H "Authorization: Bearer sig_xxx" \
    -H "Content-Type: application/json" \
    -d '{
      "query": "APPLE",
      "options": { "aggregations": ["mark_feature_type", "mark_legal_category", "filing_route", "right_kind", "scope_kind"] }
    }'
  ```

  ```typescript TypeScript theme={null}
  const results = await signa.trademarks.list({
    query: "APPLE",
    options: {
      aggregations: [
        "mark_feature_type",
        "mark_legal_category",
        "filing_route",
        "right_kind",
        "scope_kind",
      ],
    },
  });

  console.log(results.aggregations.mark_feature_type);
  // { word: 3800, figurative: 1200, combined: 647 }
  ```

  ```python Python theme={null}
  results = client.trademarks.search(
      query="APPLE",
      options={
          "aggregations": [
              "mark_feature_type",
              "mark_legal_category",
              "filing_route",
              "right_kind",
              "scope_kind",
          ],
      },
  )
  print(results.aggregations["mark_feature_type"])
  # {"word": 3800, "figurative": 1200, "combined": 647}
  ```
</CodeGroup>