Search

Full-text, phonetic, and fuzzy trademark 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, aggregations, debugging

A few advanced options live only on POST because they do not fit in a query string: options.aggregations and options.aggregations_only. Everything else (filters, strategies, pagination, highlights, include_total, sort) works identically on both.

For the full parameter reference, see List 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	Case-insensitive exact keyword match: the entire mark text must match the query exactly
phonetic	Catches sound-alikes regardless of spelling (e.g., “SIGNA” / “CYGNA” / “SYNNA”)
fuzzy	Tolerates typos and minor character differences (fuzziness is always AUTO internally)
prefix	Matches marks that start with the query text

You can restrict which strategies are used by passing the strategies array (on POST) or a comma-separated strategies= parameter (on GET):

cURL (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.

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 (GET)

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 are POST-only because they do not map cleanly to query strings. 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

{
  "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.

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.

Suggest

For autocomplete and typeahead:

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