# Trademark Search API

> Search 13M+ USPTO trademark records by mark name or owner name.
> Free tier: 50 calls/day, no signup. Paid tier: $20 = 5,000 calls/30 days via on-chain crypto payment.

## What this API does

This API provides programmatic access to the full USPTO trademark database, covering over 13 million
trademark applications and registrations. Data is sourced from official USPTO bulk files and updated
daily. It is suitable for trademark clearance searches, brand research, competitive analysis, and
legal due diligence workflows.

## Base URL

https://tmsearchapi.com

## Full machine-readable schema

https://tmsearchapi.com/openapi.json  (OpenAPI 3.x — import directly into any OpenAPI-aware tool or agent)

## Authentication

Two tiers are available:

- **Free**: No API key required. 50 requests/day per IP, resets midnight UTC. Just call any endpoint.
- **Paid**: Generate an API key with POST /api/keys, then send $20 in USDC, USDT, or DAI on
  Base Mainnet (chainId 8453) to the payment address shown in GET /api/usage. Submit the
  transaction proof in the X-Payment header (Base64-encoded JSON: transactionHash, token,
  payer, amount). Unlocks 5,000 calls valid for 30 days (rolling window).
  Set header: X-API-Key: tm_<your-key>

## Endpoints

### GET /search/mark
Search trademarks by mark (trademark name).
- q (required, string): search term — exact match tried first, then case-insensitive partial match
- limit (optional, int, 1–1000, default 100): max results to return
- Example: https://tmsearchapi.com/search/mark?q=Nike&limit=10

### GET /search/owner
Search trademarks by owner/registrant name.
- q (required, string): owner name — includes fuzzy fallback for common typos
- limit (optional, int, 1–1000, default 100): max results to return
- Example: https://tmsearchapi.com/search/owner?q=Apple+Inc&limit=25

### GET /search/combined
Search by both mark name AND owner name simultaneously (AND logic).
- mark (optional, string): trademark name search term
- owner (optional, string): owner name search term
- limit (optional, int, 1–1000, default 100): max results to return
- At least one of mark or owner must be provided.
- Example: https://tmsearchapi.com/search/combined?mark=swoosh&owner=Nike

### POST /api/keys
Generate a new API key (no request body needed). Key is prefixed with tm_ and starts with 0 credits.
Top up credits by submitting payment proof on any subsequent search request.

### GET /api/keys/verify
Check whether an API key is valid and return its current credit balance and expiry date.
- Requires X-API-Key header.
- Does NOT consume any credits. Safe to call at any time to confirm a key is working.
- Returns: {"valid": true, "credits": N, "expires": "YYYY-MM-DD"} or {"valid": false}

### GET /api/usage
Return remaining credits, reset date, and payment instructions for an API key.
- Requires X-API-Key header.

### GET /health
Return database connectivity status and environment readiness.

### GET /ping
Simple liveness check. Returns {"status": "ok"}.

## Response format (all search endpoints)

{
  "results": [
    {
      "serial_number": "string",
      "registration_number": "string",
      "status_code": "string",
      "status_date": "string",
      "mark": "string",
      "classes": "string",
      "descriptions": "string",
      "owner_name": "string",
      "owner_country": "string"
    }
  ],
  "total_count": integer,
  "query": "string",
  "search_type": "mark | owner | combined"
}

## Rate limit errors

HTTP 429 is returned when the free daily limit is exhausted. The response body includes upgrade
instructions. HTTP 402 is returned when a paid API key has no remaining credits.

## Response headers

Successful search responses always include rate/credit information in headers:
- Free tier: X-RateLimit-Limit (50), X-RateLimit-Remaining (calls left today), X-RateLimit-Reset (midnight UTC)
- Paid tier: X-Credits-Remaining (credits left in the 30-day window)

## Interactive documentation

https://tmsearchapi.com/docs  (Swagger UI — try endpoints live in a browser)