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 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/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