Python client for the Perigon API
A modern, fully‑typed Python SDK for the Perigon API, generated from the official OpenAPI specification.
Works in CPython 3.8+, PyPy, serverless runtimes, notebooks, and async frameworks.
- Type‑hinted request/response models powered by Pydantic
- Async and sync support - choose the right approach for your application
- Ships with PEP 561 type hints for excellent IDE integration
- Generated directly from https://docs.perigon.io, so it's always in sync
pip install perigon
# poetry add perigon# pipx install perigonfromperigonimportV1Api, ApiClient# Create client with API keyapi=V1Api(ApiClient(api_key="YOUR_API_KEY"))
# Alternative: environment variable or callable# api = V1Api(ApiClient(api_key=os.environ["PERIGON_API_KEY"]))# api = V1Api(ApiClient(api_key=lambda: get_api_key_from_vault()))# 🔍 Search recent news articles (sync)articles=api.search_articles(q="artificial intelligence", size=5)
print(articles.num_results, articles.articles[0].title)
# 👤 Look up a journalist by ID (sync)journalist=api.get_journalist_by_id(id="123456")
print(journalist.name)
# 🔄 Use async variant for async applicationsimportasyncioasyncdeffetch_data():
# Search articles asynchronously articles=awaitapi.search_articles_async(q="technology", size=5)
# Look up journalist asynchronouslyjournalist=awaitapi.get_journalist_by_id_async(id="123456")
returnarticles, journalist# Run in async contextarticles, journalist=asyncio.run(fetch_data())All methods return typed objects with full IDE autocompletion support.
Docs →https://docs.perigon.io/docs/overview
# Simple queryarticles=api.search_articles(q="technology", size=5)
# With date rangearticles=api.search_articles(
q="business", var_from="2025-04-01", # Note: 'from' is a reserved keyword in Pythonto="2025-04-08"
)
# Restrict to specific sourcesarticles=api.search_articles(source=["nytimes.com"])Docs →https://docs.perigon.io/docs/company-data
results=api.search_companies(name="Apple", size=5)Docs →https://docs.perigon.io/docs/journalist-data
# Search for journalistsresults=api.search_journalists1(name="Kevin", size=1)
# Get detailed informationjournalist=api.get_journalist_by_id(id=results.journalists[0].id)Docs →https://docs.perigon.io/docs/stories-overview
stories=api.search_stories(q="climate change", size=5)Docs →https://docs.perigon.io/docs/vector-endpoint
fromperigon.models.article_search_paramsimportArticleSearchParamsresults=api.vector_search_articles(
article_search_params=ArticleSearchParams(
prompt="Latest advancements in artificial intelligence",
size=5
)
)Docs →https://docs.perigon.io/docs/search-summarizer
fromperigon.models.summary_bodyimportSummaryBodysummary=api.search_summarizer(
summary_body=SummaryBody(prompt="Key developments"),
q="renewable energy", size=10
).summaryprint(summary)Docs →https://docs.perigon.io/docs/topics
topics=api.search_topics(size=10)Docs →https://docs.perigon.io/docs/wikipedia
# Search Wikipedia pageswikipedia_result=api.search_wikipedia(
q="machine learning",
size=3,
sort_by="relevance"
)
# Filter by specific criteriawikipedia_result=api.search_wikipedia(
q="artificial intelligence",
pageviews_from=100, # Only popular pages
)Docs →https://docs.perigon.io/docs/vector-wikipedia
fromperigon.models.wikipedia_search_paramsimportWikipediaSearchParamsresults=api.vector_search_wikipedia(
wikipedia_search_params=WikipediaSearchParams(
prompt="artificial intelligence and neural networks in computing",
size=3,
pageviews_from=100
)
)| Action | Code Example |
|---|---|
| Filter by source | api.search_articles(source=["nytimes.com"]) |
| Limit by date range | api.search_articles(q="business", var_from="2025-04-01", to="2025-04-08") |
| Company lookup | api.search_companies(name="Apple", size=5) |
| Summarize any query | api.search_summarizer(summary_body=SummaryBody(prompt="Key points"), q="renewable energy", size=20) |
| Semantic / vector search | api.vector_search_articles(article_search_params=ArticleSearchParams(prompt="advancements in AI", size=5)) |
| Retrieve available taxonomic topics | api.search_topics(size=10) |
| Search Wikipedia pages | api.search_wikipedia(q="machine learning", size=3, sort_by="relevance") |
| Wikipedia semantic search | api.vector_search_wikipedia(wikipedia_search_params=WikipediaSearchParams(prompt="artificial intelligence", size=3)) |
All methods have async counterparts with the _async suffix:
importasynciofromperigonimportV1Api, ApiClientasyncdefmain():
api=V1Api(ApiClient(api_key="YOUR_API_KEY"))
# Concurrent API callsarticles_task=api.search_articles_async(q="technology", size=5)
journalist_task=api.get_journalist_by_id_async(id="123456")
# Gather resultsarticles, journalist=awaitasyncio.gather(articles_task, journalist_task)
returnarticles, journalist# Run the async functionarticles, journalist=asyncio.run(main())MIT © Perigon