Updated on June 18, 2026 · Published by PatSnap Open Intelligence Team

This tutorial walks you through authenticating with the PatSnap API and running your first semantic patent search. You’ll need an API key and Python 3.8+ installed, and by the end you’ll have a working script that returns relevant patents based on natural language queries.

You will build a Python script that connects to the semantic search endpoint, authenticates using an API key, and retrieves patent results based on a text query. The script calls the /search/patent/semantic-search-patent/v2 endpoint with a simple text description, then prints key patent metadata including publication numbers, titles, assignees, and relevance scores. The output is structured JSON containing patent records ranked by semantic similarity to your search text.

Prerequisites

• Python 3.8+
• requests library (pip install requests)
• API key from PatSnap developer portal

Your API key authenticates every request

Navigate to the developer portal and sign in to your account. Go to Admin Dashboard → API Keys → Create New Key. Your API key will be shown once in the format sk-xxxxxxxxxxxxxxxxxxxx. Copy it immediately—you won’t be able to view it again. Store this key securely as an environment variable rather than hardcoding it into your scripts. The platform provides 10,000 free credits on signup with no credit card required.

Install the requests library and configure your environment

Install the requests library if you haven’t already:

pip install requests

Set your API key as an environment variable to keep it secure. On Linux or macOS, add this to your terminal session:

export PATSNAP_API_KEY="sk-xxxxxxxxxxxxxxxxxxxx"

On Windows Command Prompt:

set PATSNAP_API_KEY=sk-xxxxxxxxxxxxxxxxxxxx

You can also add this to your .bashrc, .zshrc, or system environment variables for permanent storage.

The semantic search endpoint finds patents using natural language

The semantic search endpoint lets you find patents using natural language descriptions instead of keyword searches. Create a new Python file and add this complete script:

import os
import requests

API_KEY = os.environ.get("PATSNAP_API_KEY", "YOUR_API_KEY")
BASE_URL = "https://connect.patsnap.com"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

payload = {
    "text": "battery electrolyte for electric vehicles",
    "limit": 5
}

response = requests.post(
    f"{BASE_URL}/search/patent/semantic-search-patent/v2",
    headers=headers,
    json=payload
)

data = response.json()

# Print key fields
if data.get("status"):
    print(f"Total results found: {data['data']['total_search_result_count']}")
    print(f"Results returned: {data['data']['result_count']}\n")

    for item in data["data"]["results"]:
        print(f"Relevancy: {item['relevancy']}")
        print(f"Patent Number: {item['pn']}")
        print(f"Title: {item['title']}")
        print(f"Original Assignee: {item['original_assignee']}")
        print(f"Current Assignee: {item['current_assignee']}")
        print(f"Inventor: {item['inventor']}")
        print(f"Application Date: {item['apdt']}")
        print(f"Publication Date: {item['pbdt']}")
        print("-" * 80)
else:
    print(f"Error: {data.get('error_code')}")

When you run this script successfully, the API returns JSON in this structure:

{
  "status": true,
  "error_code": 0,
  "data": {
    "result_count": 5,
    "total_search_result_count": 2000,
    "results": [
      {
        "relevancy": "80%",
        "patent_id": "uuid-placeholder",
        "pn": "US0000000A0",
        "apno": "US00/000000",
        "title": "Patent title placeholder",
        "original_assignee": "Company name placeholder",
        "current_assignee": "Company name placeholder",
        "inventor": "Inventor name placeholder",
        "apdt": 20090824,
        "pbdt": 20150317
      }
    ]
  }
}

The printed output displays each patent’s relevancy score, publication number, title, assignee information, inventor names, and key dates. The relevancy field shows how closely each patent matches your semantic query text, while pn is the standardized publication number following USPTO formatting conventions. The apdt and pbdt fields are application and publication dates respectively, returned as YYYYMMDD integers (e.g., 20090824).

Run the script and test your connection

Run the script with the example query “battery electrolyte for electric vehicles”. If you see patent results with relevancy scores and publication numbers printed to your console, you’re successfully connected. Try changing the text field to match your research area—for example, “machine learning image recognition” or “biodegradable packaging materials”—and increase the limit value to retrieve more results.

Troubleshooting

Next Steps

• Explore the full API reference documentation to discover additional search endpoints and parameters
• Try the structured patent search endpoint for more precise queries using specific patent fields like assignee, IPC classification codes, or date ranges
• Review pricing and quota information in the developer portal to plan your usage and upgrade as needed
• Process patent results with the Anthropic Claude API to summarize claims, extract technical details, or compare innovations across patents

Note: API endpoint details are based on PatSnap Open Platform documentation as of 2026. Features may change. View the latest docs.

Get Access to the PatSnap API

10,000 free credits. No credit card required.

→ Get Your API Key — sign up at open.patsnap.com/devportal/
→ Explore the API Reference — full endpoint documentation