Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.wokelo.ai/llms.txt

Use this file to discover all available pages before exploring further.

1. Overview

The Industry News Monitoring API fetches the latest news articles for a given industry topic or sector, enriched with AI-generated summaries, geographic signals, and source metadata. Results are returned synchronously in the HTTP response — no job polling required. This is a synchronous GET API — you pass a free-text topic and optional filters as URL parameters, and receive a paginated array of enriched news articles immediately. Unlike the Company News Monitoring API, which fetches news anchored to a specific company, this API accepts any natural-language topic — a sector, a technology, a theme, a geopolitical event, or a cross-company trend. The breadth of coverage is defined by the topic string and optionally narrowed by geo and date range. Each article in the response includes:
  • AI summary — a concise, machine-generated synopsis of the article’s key facts and implications
  • Geographic tags — ISO 3166-1 alpha-3 country codes identifying which geographies are relevant to the article
  • Publisher and source metadata — article URL, title, publication datetime, and source attribution
  • Article identifier — a stable numeric id for deduplication across paginated requests
Common use cases:
  • Sector monitoring for investment research — Track news on themes like “warehouse automation”, “GLP-1 drugs”, or “offshore wind” across a rolling 30-day window without being tied to a specific company
  • Geopolitical and macro intelligence — Monitor topics like “US-China trade war”, “European energy security”, or “emerging market debt” filtered to specific regions using the geo parameter
  • LP and fund reporting — Aggregate industry-level developments across portfolio sectors for quarterly reporting or LP briefings
  • Market entry and expansion research — Filter a topic to a specific country or region (e.g., “electric vehicle charging” in IND) to surface market-specific activity
  • Thematic investment screening — Use the ai_summary field to efficiently triage large volumes of sector news before reading full articles
  • Regulatory and policy tracking — Monitor topics like “data privacy regulation”, “carbon border adjustment”, or “AI legislation” with geographic narrowing to track jurisdiction-specific developments
This API is synchronous. Results are returned directly in the HTTP response — no job submission or polling required. See How Sync APIs work.

2. Quick Start

Step 1 — Make a simple request
curl --location 'https://api.wokelo.ai/api/enterprise/industry/news/?topic=Trade%20war&limit=100' \
  --header 'Authorization: Bearer <YOUR_API_TOKEN>' \
  --header 'Content-Type: application/json'
Step 2 — Narrow by geography and date range
response = requests.get(
    "https://api.wokelo.ai/api/enterprise/industry/news/",
    headers={"Authorization": "Bearer <YOUR_API_TOKEN>"},
    params={
        "topic": "Real Estate Development",
        "geo": "ARE",
        "start_date": "2026-04-01",
        "end_date": "2026-04-30",
        "limit": 100
    }
)
articles = response.json()["data"]
Step 3 — Work with the articles
for article in articles:
    geo_str = ", ".join(article.get("geo", []))
    print(f"[{geo_str}] {article['title']}")
    print(f"  {article['published_date'][:10]}")
    print(f"  {article['ai_summary'][:150]}...")
    print()

3. Authentication

All requests must include a Bearer token in the Authorization HTTP header. No other authentication method is supported.
Authorization: Bearer <YOUR_API_TOKEN>
API tokens are issued from your Wokelo account. Navigate to Account Details → API Credentials in the Wokelo dashboard to get your client id and client secret. Contact support@wokelo.ai if you do not yet have API access.
Never expose your token in client-side code, browser requests, or public repositories. A missing or invalid token returns 401 Unauthorized. A valid token without sufficient plan permissions returns 403 Forbidden.

4. Request Reference

Endpoint
GET https://api.wokelo.ai/api/enterprise/industry/news/
All parameters are passed as URL query parameters.
ParameterTypeRequiredDescription
topicstringRequiredFree-text description of the industry, sector, or theme to monitor. The query engine matches articles by relevance to this string. Specific, descriptive topics yield tighter results than broad single-word queries. Examples: "Warehouse Automation", "GLP-1 obesity drugs", "Real Estate Development", "US-China trade tariffs".
start_datestringOptionalStart of the date window for articles (YYYY-MM-DD). Inclusive.
end_datestringOptionalEnd of the date window for articles (YYYY-MM-DD). Inclusive.
limitintegerOptionalMaximum number of articles to return. Default 100, max 1000.
offsetintegerOptionalNumber of articles to skip before returning results. Default 0. Use with limit for pagination.
blacklistedstringOptionalComma-separated list of publisher domains to exclude. Include the full domain starting with https:// (e.g. "https://www.prnewswire.com/").
geostringOptionalComma-separated list of ISO 3166-1 alpha-3 country codes to filter articles by geography (e.g. "USA", "GBR,DEU,FRA", "ARE"). Returns only articles tagged with at least one of the specified countries.
Full request example:
curl --location 'https://api.wokelo.ai/api/enterprise/industry/news/?topic=Warehouse%20automation&start_date=2026-04-01&end_date=2026-04-30&geo=IND&limit=100&offset=0&blacklisted=https%3A%2F%2Fwww.prnewswire.com%2F' \
  --header 'Authorization: Bearer <YOUR_API_TOKEN>' \
  --header 'Content-Type: application/json'

5. Response

Response structure

{
  "status": "success",
  "data": [ ...article objects... ],
  "count": 14,
  "total": 14,
  "limit": 100,
  "offset": 0
}
FieldTypeDescription
statusstring"success" when the request was processed successfully.
dataarrayArray of enriched article objects.
countintegerNumber of articles returned in this response batch.
totalintegerTotal number of matching articles available across all pages (before limit and offset are applied).
limitintegerThe limit value applied to this response.
offsetintegerThe offset value applied to this response.

Article object fields

Each object in the data array contains the following fields: Article identity
FieldTypeDescription
idintegerStable numeric identifier for this article in Wokelo’s index. Use for deduplication when paginating or comparing runs across different date windows.
urlstringCanonical URL of the original article.
titlestringHeadline of the article as published.
published_datestringPublication datetime in YYYY-MM-DD HH:MM:SS format (UTC).
AI enrichment
FieldTypeDescription
ai_summarystringAI-generated 2–4 sentence summary of the article’s key facts and implications for the topic.
Source and geography
FieldTypeDescription
sourcestringWokelo’s internal signal source designation. Either "Wokelo" (directly indexed) or "Google" (sourced via search).
geostring[]Array of ISO 3166-1 alpha-3 country codes identifying the geographies covered or referenced in the article (e.g. ["USA", "CHN"]). Empty array when no country was detected.
The Industry News Monitoring API returns a leaner article object than the Company News Monitoring API. Fields like sentiment, primary_tag, secondary_tags, newsworthiness_impact, company_names, publisher, author, and scraped_text are not included in industry news responses. Use ai_summary for content triage and url to fetch the full article when needed.

Notes on the geo field

The geo array reflects countries that are mentioned or relevant in the article — not necessarily where the article was published. A single article covering US-China trade policy may have ["USA", "CHN"]. An article about a regional development project may have only one code.
  • Multi-country articles — articles covering diplomatic events, bilateral trade deals, or multinational company activity commonly list three or more country codes
  • Empty geo — some articles have an empty geo array when country detection was inconclusive; these are still returned unless you have filtered by geo
  • geo filter behaviour — when you pass geo=IND,SGP, the API returns articles tagged with IND or SGP, not exclusively articles tagged with both

Pagination notes

Industry topic queries can return very large result sets. For broad topics like “trade war” or “artificial intelligence” the total count can exceed several thousand. Always check total against count and paginate using offset until all records have been retrieved. The recommended approach is to stop when count returns 0 or len(all_articles) >= total.

6. Examples

Monitoring a sector in a specific region

Fetch all real estate development news in the UAE for a specific month — useful for generating a sector brief or LP update.
curl --location 'https://api.wokelo.ai/api/enterprise/industry/news/?topic=Real%20Estate%20Development&geo=ARE&start_date=2026-04-01&end_date=2026-04-30&limit=100' \
  --header 'Authorization: Bearer <YOUR_API_TOKEN>' \
  --header 'Content-Type: application/json'
Sample response (excerpt):
{
  "status": "success",
  "data": [
    {
      "id": 10442144,
      "ai_summary": "Nakheel has awarded contracts worth over Dh3.5 billion to construct 544 villas on Palm Jebel Ali, part of a major waterfront development in Dubai. Construction is set to start this quarter and aims for completion by late 2028, featuring smart and sustainable homes.",
      "url": "https://gulfnews.com/business/property/nakheel-awards-dh35-billion-contracts-for-palm-jebel-ali-villas-1.500520259",
      "title": "Nakheel Awards Dh3.5 Billion Contracts for 544 Palm Jebel Ali Villas in Major Dubai Waterfront Push",
      "published_date": "2026-04-27 05:20:10",
      "source": "Wokelo",
      "geo": ["ARE"]
    },
    {
      "id": 8786881,
      "ai_summary": "Dubai's real estate market experienced a 23.4% increase in property sales value in Q1 2026, with off-plan projects being the primary driver of growth.",
      "url": "https://www.constructionworld.in/latest-construction-news/real-estate-news/dubai-q1-property-sales-rise-23.4--in-value/89514",
      "title": "Dubai Q1 Property Sales Rise 23.4% in Value",
      "published_date": "2026-04-06 12:11:07",
      "source": "Wokelo",
      "geo": ["ARE"]
    }
  ],
  "count": 14,
  "total": 14,
  "limit": 100,
  "offset": 0
}

Multi-region sector sweep

Monitor a technology sector across several markets simultaneously by passing multiple geo codes. Useful for tracking a theme across different regulatory or market environments.
import requests

HEADERS = {"Authorization": "Bearer <YOUR_API_TOKEN>"}

response = requests.get(
    "https://api.wokelo.ai/api/enterprise/industry/news/",
    headers=HEADERS,
    params={
        "topic": "Electric vehicle charging infrastructure",
        "geo": "USA,GBR,DEU,FRA,IND",
        "start_date": "2026-01-01",
        "end_date": "2026-04-30",
        "limit": 200
    }
)

articles = response.json()["data"]

# Group by primary geography (first country code in the geo array)
from collections import defaultdict
by_geo = defaultdict(list)
for a in articles:
    primary = a["geo"][0] if a.get("geo") else "Unknown"
    by_geo[primary].append(a)

for country, items in sorted(by_geo.items(), key=lambda x: -len(x[1])):
    print(f"\n{country}: {len(items)} articles")
    for a in items[:2]:
        print(f"  [{a['published_date'][:10]}] {a['title']}")

Rolling 30-day monitoring pipeline

Set up a recurring pull that always covers the most recent 30 days, suitable for a weekly digest or automated feed.
import requests
from datetime import datetime, timedelta

HEADERS = {"Authorization": "Bearer <YOUR_API_TOKEN>"}

def fetch_industry_news(topic, geo=None, days=30, blacklist=None):
    end_date   = datetime.today().strftime("%Y-%m-%d")
    start_date = (datetime.today() - timedelta(days=days)).strftime("%Y-%m-%d")

    params = {
        "topic":      topic,
        "start_date": start_date,
        "end_date":   end_date,
        "limit":      200
    }
    if geo:
        params["geo"] = geo
    if blacklist:
        params["blacklisted"] = blacklist

    response = requests.get(
        "https://api.wokelo.ai/api/enterprise/industry/news/",
        headers=HEADERS,
        params=params
    )
    return response.json()

BLACKLIST = "https://www.prnewswire.com/, https://www.businesswire.com/"

topics = [
    ("Warehouse Automation", "USA,GBR,DEU"),
    ("GLP-1 obesity drugs", "USA"),
    ("Carbon border adjustment", "EU,GBR,DEU,FRA")
]

for topic, geo in topics:
    result = fetch_industry_news(topic, geo=geo, days=30, blacklist=BLACKLIST)
    print(f"\n{'='*60}")
    print(f"Topic: {topic} | Region: {geo}")
    print(f"Articles: {result['total']}")
    for a in result["data"][:3]:
        print(f"  [{a['published_date'][:10]}] {a['title']}")
        print(f"    {a['ai_summary'][:150]}...")

Paginating through large topic result sets

For broad topics, total can significantly exceed limit. Paginate using offset until all records are retrieved.
import requests

HEADERS = {"Authorization": "Bearer <YOUR_API_TOKEN>"}

PARAMS = {
    "topic":      "Artificial intelligence regulation",
    "start_date": "2026-01-01",
    "limit":      100,
    "offset":     0
}

all_articles = []

while True:
    response = requests.get(
        "https://api.wokelo.ai/api/enterprise/industry/news/",
        headers=HEADERS,
        params=PARAMS
    )
    data = response.json()
    batch = data.get("data", [])
    all_articles.extend(batch)

    fetched = len(all_articles)
    total   = data["total"]
    print(f"Fetched {fetched} / {total} articles")

    if fetched >= total or not batch:
        break

    PARAMS["offset"] += PARAMS["limit"]

# Deduplicate by article id
seen_ids  = set()
unique    = []
for a in all_articles:
    if a["id"] not in seen_ids:
        seen_ids.add(a["id"])
        unique.append(a)

print(f"\nTotal unique articles: {len(unique)}")

Comparing sector activity across geographies

Pull the same topic for multiple regions and compare article volume and recency — useful for understanding where in the world a theme is most actively developing.
import requests
from datetime import datetime, timedelta

HEADERS = {"Authorization": "Bearer <YOUR_API_TOKEN>"}

REGIONS = {
    "North America": "USA,CAN,MEX",
    "Europe":        "GBR,DEU,FRA,NLD,SWE",
    "Asia-Pacific":  "CHN,JPN,KOR,IND,AUS,SGP"
}

topic      = "Generative AI investment"
start_date = (datetime.today() - timedelta(days=90)).strftime("%Y-%m-%d")
end_date   = datetime.today().strftime("%Y-%m-%d")

print(f"Topic: {topic} | Last 90 days\n{'='*50}")

for region_name, geo in REGIONS.items():
    response = requests.get(
        "https://api.wokelo.ai/api/enterprise/industry/news/",
        headers=HEADERS,
        params={
            "topic":      topic,
            "geo":        geo,
            "start_date": start_date,
            "end_date":   end_date,
            "limit":      1          # We only need total count
        }
    )
    total = response.json().get("total", 0)
    print(f"{region_name:<20} {total:>5} articles")

JavaScript / Node.js

const fetch = require("node-fetch");

async function getIndustryNews(topic, options = {}) {
  const params = new URLSearchParams({
    topic,
    ...(options.geo        && { geo:        options.geo }),
    ...(options.startDate  && { start_date: options.startDate }),
    ...(options.endDate    && { end_date:   options.endDate }),
    ...(options.blacklisted && { blacklisted: options.blacklisted }),
    limit:  options.limit  || 100,
    offset: options.offset || 0
  });

  const response = await fetch(
    `https://api.wokelo.ai/api/enterprise/industry/news/?${params}`,
    {
      method: "GET",
      headers: {
        "Authorization": `Bearer ${process.env.WOKELO_API_KEY}`,
        "Content-Type": "application/json"
      }
    }
  );

  if (!response.ok) {
    throw new Error(`API error: ${response.status} ${response.statusText}`);
  }

  return response.json();
}

// Example: monitor warehouse automation in India and Germany
getIndustryNews("Warehouse automation", {
  geo:       "IND,DEU",
  startDate: "2026-01-01",
  endDate:   "2026-04-30"
}).then(data => {
  console.log(`Found ${data.total} articles`);
  data.data.forEach(a => {
    console.log(`[${a.geo.join(", ")}] ${a.title}`);
  });
});

7. Error Handling

The API uses standard HTTP status codes. All error responses include a JSON body with a detail or message field.
StatusMeaningCause & Resolution
200 OKSuccessArticles returned successfully.
400 Bad RequestInvalid parametersA required parameter is missing or a value is invalid — e.g. missing topic, malformed start_date, or invalid ISO country code in geo. Check the detail field.
401 UnauthorizedAuth failedThe Authorization header is missing, malformed, or contains an invalid token. Verify your key in Settings → API Keys.
403 ForbiddenInsufficient accessYour plan does not include access to this endpoint. Contact support@wokelo.ai to review your plan.
429 Too Many RequestsRate limit exceededImplement exponential back-off. The response includes a Retry-After header.
500 Internal Server ErrorServer errorRetry after a brief delay. If the issue persists, contact support@wokelo.ai.
Error response example:
{
  "status": "error",
  "detail": "The 'topic' parameter is required."
}
Retry logic with exponential back-off:
import time, requests

def fetch_industry_news_with_retry(params, api_key, max_retries=3):
    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    }
    for attempt in range(max_retries):
        try:
            response = requests.get(
                "https://api.wokelo.ai/api/enterprise/industry/news/",
                headers=headers,
                params=params,
                timeout=30
            )
            if response.status_code == 429:
                wait = 2 ** attempt   # 1s, 2s, 4s
                time.sleep(wait)
                continue
            response.raise_for_status()
            return response.json()
        except requests.exceptions.Timeout:
            if attempt == max_retries - 1:
                raise
            time.sleep(1)
    raise Exception(f"Failed after {max_retries} attempts")

8. Best Practices

Write a specific, descriptive topic — this is the single highest-impact parameter The topic field drives the entire article retrieval. A vague topic like "technology" returns an enormous, noisy result set. A specific topic describing the exact theme, technology, or event produces a tight, actionable feed:
# ❌ Too broad — will return millions of tangentially related articles
params["topic"] = "technology"

# ✅ Specific — returns a focused, high-signal result set
params["topic"] = "Warehouse automation and robotics"
params["topic"] = "US-China semiconductor export controls"
params["topic"] = "Offshore wind farm development in the North Sea"
params["topic"] = "GLP-1 weight loss drug market competition"
Use geo to narrow scope, not to replace topic specificity The geo filter restricts articles to those tagged with specific countries, but a vague topic with aggressive geo filtering can still return a noisy result set. Lead with a specific topic and use geo to reduce geographic noise:
# For India-specific EV charging — be specific in both dimensions
params = {
    "topic": "Electric vehicle charging infrastructure investment",
    "geo":   "IND"
}
Use ISO 3166-1 alpha-3 codes — not alpha-2 The geo parameter requires 3-letter codes ("USA", "GBR", "DEU") not the 2-letter equivalents ("US", "GB", "DE"). Passing alpha-2 codes will not filter correctly and may return unexpected results.
# ❌ Wrong format — 2-letter codes
params["geo"] = "US, GB"

# ✅ Correct format — 3-letter ISO codes
params["geo"] = "USA,GBR"
Set a date window for every production run Without start_date and end_date, the query returns articles across the full Wokelo index, which for active topics can mean thousands of articles. Always bound queries to the window you intend to process — 30-day windows work well for regular monitoring runs, 7-day windows for weekly digests:
from datetime import datetime, timedelta

end_date   = datetime.today().strftime("%Y-%m-%d")
start_date = (datetime.today() - timedelta(days=30)).strftime("%Y-%m-%d")
params["start_date"] = start_date
params["end_date"]   = end_date
Use article id for deduplication across runs The id field is a stable identifier for each article in Wokelo’s index. When running the same topic query on an overlapping date range (e.g. daily refreshes), deduplicate by id to avoid processing the same article twice:
seen_ids = set()
new_articles = []
for a in articles:
    if a["id"] not in seen_ids:
        seen_ids.add(a["id"])
        new_articles.append(a)
Blacklist press release aggregators to improve signal quality Wire services and press release aggregators (prnewswire.com, businesswire.com, globenewswire.com) publish high volumes of company-issued releases that can dominate topic results. Blacklisting these domains surfaces editorial journalism and independent analysis:
params["blacklisted"] = (
    "https://www.prnewswire.com/, "
    "https://www.businesswire.com/, "
    "https://www.globenewswire.com/"
)
Use ai_summary for fast triage before fetching full articles The ai_summary field provides a reliable 2–4 sentence synopsis that is sufficient for most triage decisions. Read full articles via the url field only for items that pass your relevance threshold, rather than attempting to scrape all articles in a result set. Understand the difference from Company News Monitoring The Industry API response schema is intentionally leaner — it does not include sentiment, primary_tag, secondary_tags, newsworthiness_impact, company_names, publisher, author, or scraped_text. If you need these enrichment fields, or if your monitoring is anchored to specific companies, use the Company News Monitoring API instead. The two APIs are complementary: industry monitoring for broad thematic coverage, company monitoring for entity-level depth.

Company News Monitoring

Fetch company-specific news with richer enrichment — sentiment, event categories, company mentions, and full article text.

Newsfeed

Retrieve a curated, cross-company newsfeed based on a topic, theme, or portfolio watchlist.

Industry Deep Intelligence

Generate a comprehensive AI research report on any industry — market size, competitive dynamics, key players, and outlook.

Industry Research

Run a structured, async AI research workflow on an industry topic and receive a formatted output report.

Market Map

Discover and map all companies competing in a specific market or product category.

Supporting APIs

Company Search, Request Status, and other utilities used alongside monitoring workflows.