WorldAPI — API Reference

Introduction

WorldAPI provides programmatic access to real-time news reports from around the world. Authenticate with your API key and start querying reports by city, country, or category.

All requests and responses use JSON. Include your API key as a Bearer token in the Authorization header.

Base URL

https://api.worldapi.com

All endpoints are relative to this base URL. HTTPS is required for all requests.

Rate Limits

Free

$0/mo

100

requests/day

Pro

$49/mo

5,000

requests/day

Business

$199/mo

25,000

requests/day

Enterprise

Custom

∞

requests/day

Rate Limit Headers

Header	Description
`X-RateLimit-Limit`	Total requests allowed per day
`X-RateLimit-Remaining`	Requests remaining in current window
`X-RateLimit-Reset`	Unix timestamp when the limit resets

Error Codes

Code	Meaning
400	Bad Request — Invalid parameters
401	Unauthorized — Missing or invalid token
403	Forbidden — Insufficient permissions
404	Not Found — Endpoint does not exist
409	Conflict — Resource already exists (e.g. duplicate email)
429	Too Many Requests — Rate limit exceeded
500	Internal Server Error

Error Response Format

{
  "error": "Unauthorized",
  "message": "Invalid or expired token"
}

Authentication

Account creation and login are handled through the WorldAPI Console. Once signed up, use the endpoints below to manage your account and API key programmatically.

GET /auth/me Get current user

🔒 Requires JWT

Retrieve the authenticated user's profile and usage information.

Headers

Name	Type	Required	Description
`Authorization`	string	Required	Bearer {jwt_token}

Example Request

curl https://api.worldapi.com/auth/me \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Example Response 200 OK

{
  "id": "usr_8x7k2m",
  "email": "user@example.com",
  "name": "Jane Doe",
  "plan": "pro",
  "api_key": "wapi_sk_a1b2c3d4e5f6...",
  "usage": {
    "requests_today": 142,
    "limit": 5000
  },
  "created_at": "2026-03-04T19:00:00Z"
}

Error Codes

Code	Description
401	Missing or invalid JWT token

POST /auth/rotate-key Rotate API key

🔒 Requires JWT

Invalidate your current API key and generate a new one. The old key stops working immediately.

Headers

Name	Type	Required	Description
`Authorization`	string	Required	Bearer {jwt_token}

Example Request

curl -X POST https://api.worldapi.com/auth/rotate-key \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Example Response 200 OK

{
  "api_key": "wapi_sk_n3w4p1k3y9z8...",
  "message": "API key rotated successfully. Previous key has been invalidated."
}

Error Codes

Code	Description
401	Missing or invalid JWT token

Reports

GET /reports Fetch news reports

🔑 Requires API Key

Query news reports with optional filters. Supports filtering by location, time range, text search, geo-search, category, and more. Results are returned in reverse chronological order.

Headers

Name	Type	Required	Description
`Authorization`	string	Required	Bearer {api_key}

Query Parameters

Name	Type	Required	Description
`lat`	float	Optional	Latitude of search center (use with `lon` and `radius`)
`lon`	float	Optional	Longitude of search center
`radius`	integer	Optional	Search radius in meters (≥1, use with `lat`/`lon`)
`min_time`	integer	Optional	Unix timestamp — only reports after this time
`max_time`	integer	Optional	Unix timestamp — only reports before this time
`term`	string	Optional	Search term to filter by title/summary (case-insensitive)
`category`	string	Optional	Filter by category (e.g. "politics", "technology", "conflict")
`country`	string	Optional	Filter by country name (e.g. "US", "United Kingdom")
`city`	string	Optional	Filter by city name (e.g. "San Francisco")
`state`	string	Optional	Filter by state name (e.g. "California")
`continent`	string	Optional	Filter by continent: `africa`, `asia`, `europe`, `north_america`, `south_america`, `oceania`, `antarctica`
`family_friendly`	boolean	Optional	Filter by family-friendly status
`feed_type`	string	Optional	Filter by feed type
`limit`	integer	Optional	Number of results to return. Default: 20, Max: 100
`offset`	integer	Optional	Number of results to skip for pagination. Default: 0

Example Request — Filter by Country & Category

curl "https://api.worldapi.com/reports?country=US&category=technology&limit=5" \
  -H "Authorization: Bearer wapi_sk_a1b2c3d4e5f6..."

Example Request — Geo Search (50km around San Francisco)

curl "https://api.worldapi.com/reports?lat=37.7749&lon=-122.4194&radius=50000&limit=10" \
  -H "Authorization: Bearer wapi_sk_a1b2c3d4e5f6..."

Example Request — Text Search

curl "https://api.worldapi.com/reports?term=artificial%20intelligence&continent=europe&limit=10" \
  -H "Authorization: Bearer wapi_sk_a1b2c3d4e5f6..."

Example Response 200 OK

{
  "reports": [
    {
      "id": "rpt_3k8m2x",
      "headline": "AI Chip Exports Face New Restrictions",
      "summary": "The Commerce Department announced new export controls on advanced AI semiconductors...",
      "city": "Washington",
      "country": "US",
      "category": "technology",
      "source": "Reuters",
      "source_url": "https://reuters.com/...",
      "reported_at": "2026-03-04T18:30:00Z",
      "created_at": "2026-03-04T18:32:14Z"
    },
    {
      "id": "rpt_9p1n4v",
      "headline": "Silicon Valley Startup Raises $2B Series C",
      "summary": "A leading robotics company secured one of the largest funding rounds...",
      "city": "San Francisco",
      "country": "US",
      "category": "technology",
      "source": "TechCrunch",
      "source_url": "https://techcrunch.com/...",
      "reported_at": "2026-03-04T17:15:00Z",
      "created_at": "2026-03-04T17:18:02Z"
    }
  ],
  "total": 847
}

Error Codes

Code	Description
400	Invalid query parameters (e.g. limit > 100)
401	Missing or invalid API key
429	Rate limit exceeded

Polymarket

GET /polymarket/news Find reports relevant to a market

🔑 Requires API Key

Find WorldAPI news reports relevant to a Polymarket prediction market. Provide a market URL, slug, or free-text search terms. Returns market context along with matching reports ranked by relevance.

Headers

Name	Type	Required	Description
`Authorization`	string	Required	Bearer {api_key}

Query Parameters

Name	Type	Required	Description
`url`	string	Optional	Full Polymarket market URL
`slug`	string	Optional	Polymarket market slug (e.g. "will-bitcoin-hit-100k-2026")
`q`	string	Optional	Free-text search terms to match against markets
`limit`	integer	Optional	Number of matching reports to return. Default: 10, Max: 50

At least one of url, slug, or q is required.

Example Request

curl "https://api.worldapi.com/polymarket/news?slug=will-bitcoin-hit-100k-2026&limit=5" \
  -H "Authorization: Bearer wapi_sk_a1b2c3d4e5f6..."

Example Response 200 OK

{
  "market": {
    "slug": "will-bitcoin-hit-100k-2026",
    "title": "Will Bitcoin hit $100k in 2026?",
    "url": "https://polymarket.com/event/will-bitcoin-hit-100k-2026"
  },
  "reports": [
    {
      "id": "rpt_7f2x9q",
      "headline": "Bitcoin Surges Past $92k on ETF Inflows",
      "summary": "Record institutional buying pushes Bitcoin to new yearly highs...",
      "category": "finance",
      "country": "US",
      "source": "Bloomberg",
      "reported_at": "2026-03-14T14:20:00Z",
      "relevance_score": 0.94
    }
  ],
  "total": 23
}

Error Codes

Code	Description
400	Missing required parameter (url, slug, or q)
401	Missing or invalid API key
429	Rate limit exceeded

GET /polymarket/markets Find markets relevant to a report

🔑 Requires API Key

Find Polymarket prediction markets relevant to a WorldAPI news report. Provide a report ID or free-text search terms. Returns report context along with matching markets and their live YES/NO prices.

Headers

Name	Type	Required	Description
`Authorization`	string	Required	Bearer {api_key}

Query Parameters

Name	Type	Required	Description
`report_id`	string	Optional	WorldAPI report ID (e.g. "rpt_3k8m2x")
`q`	string	Optional	Free-text search terms to match against markets
`limit`	integer	Optional	Number of matching markets to return. Default: 10, Max: 50

At least one of report_id or q is required.

Example Request

curl "https://api.worldapi.com/polymarket/markets?report_id=rpt_3k8m2x&limit=5" \
  -H "Authorization: Bearer wapi_sk_a1b2c3d4e5f6..."

Example Response 200 OK

{
  "report": {
    "id": "rpt_3k8m2x",
    "headline": "AI Chip Exports Face New Restrictions",
    "category": "technology",
    "country": "US"
  },
  "markets": [
    {
      "slug": "us-china-chip-ban-2026",
      "title": "Will the US ban all AI chip exports to China in 2026?",
      "url": "https://polymarket.com/event/us-china-chip-ban-2026",
      "yes_price": 0.32,
      "no_price": 0.68,
      "volume": 1250000,
      "relevance_score": 0.91
    }
  ],
  "total": 8
}

Error Codes

Code	Description
400	Missing required parameter (report_id or q)
401	Missing or invalid API key
429	Rate limit exceeded