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
code
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:
ts
import { Configuration, V1Api } from "@goperigon/perigon-ts";
const perigon = new V1Api(new Configuration({ apiKey: process.env.PERIGON_API_KEY }));
Python:
python
from perigon import V1Api, ApiClient api = V1Api(ApiClient(api_key=os.environ["PERIGON_API_KEY"]))
Go:
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() |
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:
ts
const { articles } = await perigon.searchArticles({ q: "AI", size: 10, sortBy: "date" });
Python:
python
result = api.search_articles(q="AI", size=10, sort_by="date")
Go:
go
result, err := client.All.List(ctx, perigon.AllListParams{
Q: perigon.String("AI"),
Size: perigon.Int(10),
SortBy: perigon.AllEndpointSortByDate,
})
Vector Search
TypeScript:
ts
const results = await perigon.vectorSearchArticles({
articleSearchParams: { prompt: "impact of AI on healthcare", size: 5 },
});
Python:
python
from perigon.models import ArticleSearchParams
results = api.vector_search_articles(
article_search_params=ArticleSearchParams(prompt="impact of AI on healthcare", size=5)
)
Go:
go
results, err := client.Vector.News.Search(ctx, perigon.VectorNewsSearchParams{
Prompt: "impact of AI on healthcare",
Size: perigon.Int(5),
})
Error Handling
TypeScript:
ts
try {
const result = await perigon.searchArticles({ q: "test" });
} catch (error) {
if (error.status === 429) console.error("Rate limited");
}
Python:
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:
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
- •Python
fromkeyword: Usevar_frominstead offromfor date filtering (Python reserved word). - •Python POST body params: Vector search and summarization require model objects (
ArticleSearchParams,SummaryBody,WikipediaSearchParams). - •Go optional fields: Use
perigon.String(),perigon.Int(),perigon.Float(),perigon.Time()constructors for optional parameters. - •Go retries: Built-in exponential backoff (2 retries by default). Override with
option.WithMaxRetries(). - •TypeScript middleware: Use
Configuration({ middleware: [...] })for request/response hooks.
How to Use References
Read individual reference files for detailed SDK-specific documentation:
code
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)