Search

Signa’s search supports full-text, phonetic, fuzzy, and prefix matching tuned specifically for trademark names.

Choosing GET or POST

The trademarks endpoint is exposed under both GET /v1/trademarks and POST /v1/trademarks. Both methods call the same service and return the same response shape. Pick whichever fits your call site.

Method	When to use
`GET /v1/trademarks`	Quick queries, curl exploration, URL sharing, browser and wget use, simple filters
`POST /v1/trademarks`	Complex queries, long filter lists, debugging

Everything (filters, strategies, pagination, highlights, include_total, sort, aggregations) works identically on both. On GET, aggregations is a comma-separated list and aggregations_only a boolean query parameter; on POST they live under options. For the full parameter reference, see Search Trademarks. The sections below show concrete usage patterns you can copy into your own code.

Search Strategies

By default, every search runs exact and fuzzy strategies simultaneously and merges the results. For comprehensive clearance searches, use all four:

Strategy	What it does
`exact`	Whole-mark match: the entire mark text must equal the query after folding case and accents. Also matches serial and registration numbers
`phonetic`	Catches sound-alikes regardless of spelling (e.g., “SIGNA” / “CYGNA” / “SYNNA”)
`fuzzy`	Tolerates a single-character typo for single words of 4+ characters and a second edit for longer words. The first one or two letters stay fixed; `ranking_profile=v11` also reaches a different first letter for words of 5+ characters (`timber` finds `LIMBER`). Also covers synonym and phrase matches, so it can return marks that contain the query
`prefix`	Matches marks that start with the query text

Only the strategies you pass run. strategies=exact returns whole-mark matches only; it never returns a longer mark that merely contains the query. Whole-mark matching folds lookalike characters (homoglyphs), so strategies=exact for timber also returns TIMB3R, labeled homoglyph; match=exact does not. match_explanation.strategies_matched reports finer labels (normalized, phrase, synonym, identifier, …), and each one belongs to a strategy listed in search_meta.strategies_used. strategies applies to the default match=similar mode only. The deterministic modes (match=exact, starts_with, ends_with, contains) take no strategies and return 400 validation_error if you send them. You can restrict which strategies are used by passing the strategies array (on POST) or a comma-separated strategies= parameter (on GET):

curl -G "https://api.signa.so/v1/trademarks" \
  -H "Authorization: Bearer $SIGNA_API_KEY" \
  --data-urlencode "q=signa" \
  --data-urlencode "strategies=exact,phonetic"

curl -X POST https://api.signa.so/v1/trademarks \
  -H "Authorization: Bearer $SIGNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "signa",
    "strategies": ["exact", "phonetic"]
  }'

import { Signa } from "@signa-so/sdk";

const signa = new Signa({ api_key: process.env.SIGNA_API_KEY });

// GET-style: flat params via trademarks.list()
const results = await signa.trademarks.list({
  q: "signa",
  strategies: ["exact", "phonetic"],
});

// POST-style: same query, via trademarks.search()
const searched = await signa.trademarks.search({
  query: "signa",
  strategies: ["exact", "phonetic"],
});

If you omit strategies, exact and fuzzy are used. For comprehensive trademark clearance searches, pass all four strategies explicitly: exact,phonetic,fuzzy,prefix.

There is no user-controllable fuzziness parameter. Fuzzy matching always uses AUTO internally, which adjusts edit distance based on the length of the query term.

Checking many exact spellings at once

When you already have the list of spellings to check (every one-letter variant of a word, a batch of candidate names), send them as q_any instead of one match=exact request per term. One request returns every mark that exactly equals any term, each hit tagged with matched_terms, and one page costs the same as any search page. See Several exact terms.

cURL (GET)

curl -G "https://api.signa.so/v1/trademarks" \
  -H "Authorization: Bearer $SIGNA_API_KEY" \
  --data-urlencode "q_any=signa,sigma,cygna"

Filtering

Narrow results with filters. On POST, filters are nested under a filters object. On GET, they are flat query parameters using comma-separated values for arrays and flat underscore operators for date ranges.

curl -G "https://api.signa.so/v1/trademarks" \
  -H "Authorization: Bearer $SIGNA_API_KEY" \
  --data-urlencode "q=signa" \
  --data-urlencode "offices=US,EM" \
  --data-urlencode "nice_classes=9,42" \
  --data-urlencode "status_stage=registered" \
  --data-urlencode "filing_date_gte=2020-01-01"

curl -X POST https://api.signa.so/v1/trademarks \
  -H "Authorization: Bearer $SIGNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "signa",
    "filters": {
      "offices": ["US", "EM"],
      "nice_classes": [9, 42],
      "status_stage": ["registered"],
      "filing_date": { "gte": "2020-01-01" }
    }
  }'

// GET-style: trademarks.list() takes filters as flat top-level params
const listed = await signa.trademarks.list({
  q: "signa",
  offices: ["US", "EM"],
  nice_classes: [9, 42],
  status_stage: ["registered"],
  filing_date_gte: "2020-01-01",
});

// POST-style: trademarks.search() nests the same filters under `filters`
const searched = await signa.trademarks.search({
  query: "signa",
  filters: {
    offices: ["US", "EM"],
    nice_classes: [9, 42],
    status_stage: ["registered"],
    filing_date: { gte: "2020-01-01" },
  },
});

Office codes are uppercase WIPO ST.3 two-letter codes: US (USPTO), EM (EUIPO), WO (WIPO), CA, SG, SE, CH, FR, AU, NO. Legacy lowercase codes (uspto, euipo, …) are accepted on requests permanently, and EU is accepted as an alias for EM. Responses always use the ST.3 form. Office display acronyms (e.g. IPA, IGE-IPI, INPI) are not an accepted input vocabulary — acronyms are not unique across offices; use ST.3 or legacy codes.

The two methods use different shapes. signa.trademarks.list() (GET) takes filters as flat top-level params, matching the query-string form. signa.trademarks.search() (POST) nests them under filters. Passing offices, nice_classes, status_stage, or other filter keys at the top level of a POST body returns a validation_error with unrecognized_keys. There is also no top-level search_type or type field: strategy selection happens through the strategies array.

Date filter operators:

Operator	Meaning
`gte`	Greater than or equal (from date, inclusive)
`lt`	Less than (to date, exclusive)

You can use both together for a range: "filing_date": { "gte": "2020-01-01", "lt": "2025-01-01" } (POST) or filing_date_gte=2020-01-01&filing_date_lt=2025-01-01 (GET).

Aggregations

Aggregations work on both methods: ?aggregations=office_code,status_stage on GET, or options.aggregations on POST. Bucket lists are top-N per field (for example 50 offices, 45 Nice classes, 250 owner countries); the document counts inside each bucket are not capped at 10,000 the way total_count is. An aggregation request is billed as one search page whether or not it returns documents. Available aggregation fields:

Field	Description
`office_code`	Counts by trademark office
`jurisdiction_code`	Counts by jurisdiction
`nice_classes`	Counts by Nice classification
`status_stage`	Counts by status stage
`filing_year`	Counts by filing year
`mark_feature_type`	Counts by mark type (word, figurative, etc.)
`mark_legal_category`	Counts by legal category (trademark, certification, etc.)
`filing_route`	Counts by filing route (direct_national, madrid, etc.)
`right_kind`	Counts by right kind
`scope_kind`	Counts by scope kind
`owner_id`	Counts by owner (top 50 owners only)
`entity_count`	`{ "value": n }`: distinct parties across offices; unresolved owners count once per office record (use this for crowding)
`owner_count`	`{ "value": n }`: distinct owner records; owner records are per office

{
  "query": "signa",
  "options": {
    "aggregations": ["office_code", "status_stage", "nice_classes"]
  }
}

To get only the counts with no result documents, add "aggregations_only": true to options.

How filters apply to aggregations

By default every aggregation counts the same set as the results: q, the match mode, and every filter. For a single-valued field such as office_code or status_stage, the buckets add up to total_count (multi-valued fields such as nice_classes or owner_id can add up to more, because one mark lands in several buckets). aggregations_only=true follows the same rule. For a drill-down sidebar, set aggregation_mode=exclude_own_filter (options.aggregation_mode on POST). Each aggregation then applies every filter except its own: with offices=US&nice_classes=25, the office_code buckets ignore offices but still respect nice_classes, so the sidebar can show how many marks the other offices would add. The results and total_count still respect every filter.

# Counts for the live US marks in class 25 that match "outer banks"
curl -G "https://api.signa.so/v1/trademarks" \
  -H "Authorization: Bearer $SIGNA_API_KEY" \
  --data-urlencode "q=outer banks" \
  --data-urlencode "offices=US" \
  --data-urlencode "nice_classes=25" \
  --data-urlencode "status_primary=active,pending" \
  --data-urlencode "aggregations=office_code,status_stage" \
  --data-urlencode "aggregations_only=true" \
  --data-urlencode "include_total=true"

Response Scoring

Search results include a relevance_score field, which is a normalized score from 0 to 100 (higher is more relevant). Results are sorted by relevance score in descending order by default. If you specify an explicit sort, relevance scoring is disabled and relevance_score is null.

Picking classes to filter on

If you do not know which Nice classes a query should be scoped to, send the description to POST /v1/classifications/suggest and feed the returned class_number values into nice_classes. It takes free text (“men’s running shoes, cushioned sole”) and returns ranked classes with a confidence and a rationale, so you can show the user why a class was picked. Ambiguous input comes back with ambiguous: true and a clarifying question instead of a guess.

Suggest

GET /v1/trademarks/suggest is an internal typeahead. It is not part of the published OpenAPI spec and its shape can change without notice. Use GET /v1/trademarks for search.

For autocomplete and typeahead on internal keys:

GET /v1/trademarks/suggest?q=sig&limit=10

Getting started

Core concepts

Build with AI

Data

Monitoring

Working with the API

Use cases

Choosing GET or POST

Search Strategies

Checking many exact spellings at once

Filtering

Aggregations

How filters apply to aggregations

Response Scoring

Picking classes to filter on

Suggest

​Choosing GET or POST

​Search Strategies

​Checking many exact spellings at once

​Filtering

​Aggregations

​How filters apply to aggregations

​Response Scoring

​Picking classes to filter on

​Suggest

Choosing GET or POST

Search Strategies

Checking many exact spellings at once

Filtering

Aggregations

How filters apply to aggregations

Response Scoring

Picking classes to filter on

Suggest