perigon-api-best-practices（perigon API 最佳实践）

Perigon API Best Practices

Comprehensive guide for building with the Perigon News Intelligence API. Covers all endpoints, query patterns, and integration best practices.

When to Apply

Reference these guidelines when:

• Searching or filtering news articles by keyword, topic, category, date, source, sentiment, or location
• Tracking evolving news stories and clustered article groups
• Generating AI-powered summaries of news coverage
• Performing semantic/vector search over news articles or Wikipedia content
• Querying the Wikipedia knowledge base for structured page data
• Looking up people, companies, journalists, or media sources
• Browsing available topics and categories
• Building dashboards, alerts, or monitoring tools powered by news data
• Integrating Perigon into any application or AI agent workflow

API Overview

Base URL: https://api.perigon.io

Authentication

The API key can be passed in two ways:

1. Query parameter: ?apiKey=YOUR_API_KEY
2. Header: x-api-key: YOUR_API_KEY

Best practices:

• Store the API key in an environment variable (e.g., PERIGON_API_KEY). Never hardcode it.
• Prefer the header method (x-api-key) to keep keys out of URLs and logs.
• Get your API key at perigon.io.

Endpoint Selection Guide

Choose the right endpoint based on the task:

Need individual articles? → /v1/articles/all
Need grouped stories with summaries? → /v1/stories/all
Need to track how a story evolves over time? → /v1/stories/history
Need an AI-generated summary of coverage? → /v1/summarize
Need semantic similarity search for news? → /v1/vector/news/all
Need Wikipedia knowledge? → /v1/wikipedia/all
Need semantic search over Wikipedia? → /v1/vector/wikipedia/all
Need person/company/journalist/source info? → /v1/people|companies|journalists|sources/all
Need to browse available topics? → /v1/topics/all

Core Query Patterns

Text Search (q parameter)

The q parameter searches across title, description, and content. It supports:

• Boolean operators: AND, OR, NOT
• Exact phrases: "climate change"
• Wildcards: * (multiple chars), ? (single char)
• Combining: "electric vehicles" AND (Tesla OR Rivian) NOT recalls

Date Filtering

• from / to — Filter by publication date (ISO 8601 or yyyy-mm-dd)
• addDateFrom / addDateTo — Filter by ingestion date
• refreshDateFrom / refreshDateTo — Filter by last-updated date

Pagination

• page — Page number (starts at 0)
• size — Results per page
• Set showNumResults=true to get total counts (slightly slower)

Sentiment Filtering

Filter by sentiment scores (0.0 to 1.0):

• positiveSentimentFrom / positiveSentimentTo
• negativeSentimentFrom / negativeSentimentTo
• neutralSentimentFrom / neutralSentimentTo

Array Filters (OR logic)

Many filters accept arrays and combine with OR logic: category, topic, source, language, country, label, personName, companyDomain, companySymbol, journalistId, medium, sourceGroup

Exclude Filters (AND-exclude logic)

Prefix any array filter with exclude to remove matches: excludeCategory, excludeTopic, excludeSource, excludeLanguage, etc.

Vector Search (Semantic)

For natural language queries that don't map well to keyword search, use the vector endpoints:

News: POST /v1/vector/news/all — searches articles from the last 6 months by semantic similarity.

Wikipedia: POST /v1/vector/wikipedia/all — searches Wikipedia page sections by semantic similarity.

Both accept a prompt (natural language query), page, size, and a filter object for structured filtering with nested AND/OR/NOT logic.

How to Use References

Read individual reference files for detailed endpoint documentation:

references/authentication.md        — API key setup and security
references/articles-search.md       — /v1/articles/all deep dive
references/stories-clustering.md    — /v1/stories/all deep dive
references/stories-history.md       — /v1/stories/history deep dive
references/smart-summaries.md       — /v1/summarize deep dive
references/vector-search.md         — /v1/vector/news/all and /v1/vector/wikipedia/all
references/wikipedia-knowledge.md   — /v1/wikipedia/all deep dive
references/people-companies.md      — /v1/people/all and /v1/companies/all
references/journalists-sources.md   — /v1/journalists/all and /v1/sources/all
references/topics-categories.md     — /v1/topics/all and category taxonomy
references/pagination-filtering.md  — Common query patterns and pagination
references/error-handling.md        — HTTP status codes and retry logic
references/rate-limits.md           — Rate limit management

Each reference file contains:

• Endpoint URL and HTTP method
• All query/body parameters with types and descriptions
• Example requests (curl) and response JSON
• Common patterns and best practices
• When to use this endpoint vs. alternatives

Best Practices Summary

1. Start narrow, then broaden — Use specific filters first, then relax constraints if results are too few.
2. Prefer from/to over addDateFrom/addDateTo for publication-date filtering unless you specifically need ingestion-date filtering.
3. Use showReprints=false to deduplicate wire-service content (AP, Reuters) that appears on multiple sites.
4. Use sourceGroup (e.g., top100, top25tech) for quality-filtered results.
5. Combine endpoints — Use /v1/stories/all to find story clusters, then /v1/articles/all with clusterId for all articles in a story.
6. Use vector search for intent-based queries — When the user's query is conversational or conceptual rather than keyword-based.
7. Use Wikipedia endpoints for factual background — Combine with news search to enrich coverage with encyclopedic context.
8. Handle pagination properly — Always check numResults and iterate pages when building comprehensive datasets.
9. Cache strategically — News data changes frequently, but entity data (people, companies, sources) changes slowly.
10. Respect rate limits — Implement exponential backoff on 429 responses.

External References

• Perigon Documentation
• Perigon API Reference
• Perigon Go SDK