Perigon SDKs Best Practices

Guide for using the official Perigon SDKs to integrate the Perigon News Intelligence API into TypeScript/Node.js, Python, and Go applications.

When to Apply

Reference these guidelines when:

• Installing or setting up a Perigon SDK in a new or existing project
• Initializing the Perigon client and configuring authentication
• Calling any Perigon API endpoint through an SDK (articles, stories, vector search, summarizer, Wikipedia, entities)
• Handling errors, retries, or rate limits from SDK calls
• Choosing which SDK to use for a given project or runtime
• Writing async code with the Python SDK or context-based code with the Go SDK
• Constructing typed request parameters or parsing typed responses

SDK Selection Guide

TypeScript/JavaScript project?  → @goperigon/perigon-ts
Python project?                 → perigon (PyPI)
Go project?                     → github.com/goperigon/perigon-go-sdk/v2

All three SDKs cover the same API surface. Choose based on your project language.

SDK Comparison

| | TypeScript | Python | Go | |---|---|---|---| | Package | @goperigon/perigon-ts | perigon | github.com/goperigon/perigon-go-sdk/v2 | | Install | npm install @goperigon/perigon-ts | pip install perigon | go get github.com/goperigon/perigon-go-sdk/v2 | | Client init | new V1Api(new Configuration({apiKey})) | V1Api(ApiClient(api_key=...)) | perigon.NewClient(option.WithAPIKey(...)) | | Method style | perigon.searchArticles({...}) | api.search_articles(...) | client.All.List(ctx, params) | | Async | Native Promises | _async suffix methods | Context-based | | Type system | Full TS types | Pydantic models, PEP 561 | Strongly-typed with param.Opt[T] | | Error type | ResponseError | ApiException | *perigon.Error | | Retries | Manual | Manual | Built-in (default 2) |

Authentication

All SDKs read the API key from the PERIGON_API_KEY environment variable by default. You can also pass it explicitly:

TypeScript:

import { Configuration, V1Api } from "@goperigon/perigon-ts";
const perigon = new V1Api(new Configuration({ apiKey: process.env.PERIGON_API_KEY }));

Python:

from perigon import V1Api, ApiClient
api = V1Api(ApiClient(api_key=os.environ["PERIGON_API_KEY"]))

Go:

client := perigon.NewClient() // reads PERIGON_API_KEY env var
// or explicitly:
client := perigon.NewClient(option.WithAPIKey("your-key"))

Endpoint-to-Method Mapping

| API Endpoint | TypeScript | Python | Go | |---|---|---|---| | GET /v1/articles/all | searchArticles() | search_articles() | client.All.List() | | GET /v1/stories/all | searchStories() | search_stories() | client.Stories.List() | | GET /v1/stories/history | getStoryHistory() | get_story_history() | — | | POST /v1/summarize | searchSummarizer() | search_summarizer() | client.Summarize.New() | | POST /v1/vector/news/all | vectorSearchArticles() | vector_search_articles() | client.Vector.News.Search() | | GET /v1/wikipedia/all | searchWikipedia() | search_wikipedia() | client.Wikipedia.Search() | | POST /v1/vector/wikipedia/all | vectorSearchWikipedia() | vector_search_wikipedia() | client.Wikipedia.VectorSearch() | | GET /v1/companies/all | searchCompanies() | search_companies() | client.Companies.List() | | GET /v1/people/all | searchPeople() | search_people() | client.People.List() | | GET /v1/journalists/all | searchJournalists() | search_journalists() | client.Journalists.List() | | GET /v1/journalists/{id} | getJournalistById() | get_journalist_by_id() | client.Journalists.Get() | | GET /v1/sources/all | searchSources() | search_sources() | client.Sources.List() | | GET /v1/topics/all | searchTopics() | search_topics() | client.Topics.List() |

Common Patterns

Search Articles

TypeScript:

const { articles } = await perigon.searchArticles({ q: "AI", size: 10, sortBy: "date" });

Python:

result = api.search_articles(q="AI", size=10, sort_by="date")

Go:

result, err := client.All.List(ctx, perigon.AllListParams{
    Q:      perigon.String("AI"),
    Size:   perigon.Int(10),
    SortBy: perigon.AllEndpointSortByDate,
})

Story History

TypeScript:

const { results } = await perigon.getStoryHistory({
  clusterId: ["911860d569ca464698c0beec0697f694"],
  changelogExists: true,
  size: 10,
});

Python:

result = api.get_story_history(
    cluster_id=["911860d569ca464698c0beec0697f694"],
    changelog_exists=True,
    size=10,
)

Go: Not yet available in the Go SDK. Use the REST API directly or the TypeScript/Python SDK.

Vector Search

TypeScript:

const results = await perigon.vectorSearchArticles({
    articleSearchParams: { prompt: "impact of AI on healthcare", size: 5 },
});

Python:

from perigon.models import ArticleSearchParams
results = api.vector_search_articles(
    article_search_params=ArticleSearchParams(prompt="impact of AI on healthcare", size=5)
)

Go:

results, err := client.Vector.News.Search(ctx, perigon.VectorNewsSearchParams{
    Prompt: "impact of AI on healthcare",
    Size:   perigon.Int(5),
})

Error Handling

TypeScript:

try {
    const result = await perigon.searchArticles({ q: "test" });
} catch (error) {
    if (error.status === 429) console.error("Rate limited");
}

Python:

from perigon.exceptions import ApiException
try:
    result = api.search_articles(q="test")
except ApiException as e:
    print(f"HTTP {e.status}: {e.body}")

Go:

result, err := client.All.List(ctx, perigon.AllListParams{Q: perigon.String("test")})
if err != nil {
    var apierr *perigon.Error
    if errors.As(err, &apierr) {
        fmt.Printf("HTTP %d\n", apierr.StatusCode)
    }
}

SDK-Specific Gotchas

1. Python from keyword: Use var_from instead of from for date filtering (Python reserved word).
2. Python POST body params: Vector search and summarization require model objects (ArticleSearchParams, SummaryBody, WikipediaSearchParams).
3. Go optional fields: Use perigon.String(), perigon.Int(), perigon.Float(), perigon.Time() constructors for optional parameters.
4. Go retries: Built-in exponential backoff (2 retries by default). Override with option.WithMaxRetries().
5. TypeScript middleware: Use Configuration({ middleware: [...] }) for request/response hooks.

How to Use References

Read individual reference files for detailed SDK-specific documentation:

references/typescript-sdk.md  — Full @goperigon/perigon-ts reference
references/python-sdk.md      — Full perigon Python SDK reference
references/go-sdk.md          — Full perigon-go-sdk/v2 reference

Each reference contains:

• Installation and setup instructions
• Complete method reference with all parameters
• Code examples for every endpoint
• Error handling patterns
• Advanced features (middleware, async, retries, pagination)

External References

• TypeScript SDK — GitHub
• Python SDK — GitHub
• Go SDK — GitHub
• Perigon API Documentation
• Perigon API Reference