Historical Data API Documentation

This page provides a comprehensive overview of the API endpoints which serves historical data. Please note that the API is currently closed. If you wish to use the API, you may contact our support team to activate the API for free.

Base URL

The base URL for all API endpoints is http://api.polydataexplore.org (Experiemental).

---

1. Get All Events

Retrieves a list of all available event data.

Endpoint

GET /events

Description

This endpoint returns the entire dataset of processed events as a JSON array. If the data is not yet loaded, it will return a 404 status code.

Request

No request body or parameters are required.

Response

• Status Code: 200 OK
  • Body: A JSON array of event objects.

    [
    {
        "id": 1,
        "title": "Test Event A",
        "category": "Sports",
        "volume24hr": 15000,
        "closed": false,
        "tags": ["football"],
        "markets": [
            {
                "slug": "test-market-a",
                "question": "Will A happen?"
            }
        ]
    },
    {
        "id": 2,
        "title": "Another Event B",
        "category": "Politics",
        "volume24hr": 5000,
        "closed": true,
        "tags": ["election"],
        "markets": [
            {
                "slug": "test-market-b",
                "question": "Will B happen?"
            }
        ]
    }
    // ... more event objects
    ]
    

• Status Code: 404 Not Found
  • Body:

    {
    "message": "Data not yet loaded or no events found."
    }
    

Example Usage (Python Requests)

import requests

try:
    response = requests.get('http://api.polydataexplore.org/events')
    response.raise_for_status() 
    data = response.json()
    print(data)
except requests.exceptions.RequestException as e:
    print(f"Error fetching events: {e}")
    if response.status_code:
        print(f"Status Code: {response.status_code}")
        print(f"Response Body: {response.text}")

---

2. Filter Events

Filters the event data based on specified criteria.

Endpoint

POST /events/filter

Description

This endpoint allows you to apply various filters to the event dataset. The filters are provided in the request body as a JSON object. The filtering logic supports exact matches for strings, partial matches for strings, and numerical comparisons (greater than, less than, equal to) for integers, as well as boolean checks.

Request

• Method: POST
• Content-Type: application/json
• Body: A JSON object where keys represent the filter criteria and values are the desired filter values.

Filter Parameter Format

The filter keys follow a specific format: {field_name}_{comparison_operator}.

• Text Input (Exact Match):
  • Format: {field_name}_exact
  • Example: "category_exact": "Sports"
• Text Input (Partial Match):
  • Format: {field_name}_partial
  • Example: "title_partial": "World Cup" (case-insensitive)
• Numerical Input (Comparisons):
  • Format: {field_name}_{comparison}
  • comparison can be: gt (greater than), lt (less than), eq (equal to)
  • Example: "volume24hr_gt": 10000, "id_eq": 5
• Boolean Input:
  • Format: {field_name} (no operator needed)
  • Example: "closed": true

Supported Filterable Fields

Field Name	Type	Supported Operators	Description
id	int	gt, lt, eq	Unique identifier for the event.
ticker	str	partial, exact	Event ticker symbol.
slug	str	partial, exact	URL-friendly identifier.
title	str	partial, exact	Title of the event.
description	str	partial, exact	Description of the event.
resolutionSource	str	partial, exact	Source of resolution for the event.
createdAt	int	gt, lt, eq	Unix timestamp of creation.
startDate	int	gt, lt, eq	Unix timestamp of start date.
endDate	int	gt, lt, eq	Unix timestamp of end date.
closedTime	int	gt, lt, eq	Unix timestamp when event was closed.
closed	bool	(direct value)	Indicates if the event is closed.
archived	bool	(direct value)	Indicates if the event is archived.
new	bool	(direct value)	Indicates if the event is new.
featured	bool	(direct value)	Indicates if the event is featured.
restricted	bool	(direct value)	Indicates if the event is restricted.
liquidity	int	gt, lt, eq	Total liquidity.
openInterest	int	gt, lt, eq	Total open interest.
category	str	partial, exact	Event category (e.g., "Sports", "Politics").
competitive	int	gt, lt, eq	Competitive score/value.
volume24hr	int	gt, lt, eq	Volume in the last 24 hours.
volume1wk	int	gt, lt, eq	Volume in the last 1 week.
volume1mo	int	gt, lt, eq	Volume in the last 1 month.
volume1yr	int	gt, lt, eq	Volume in the last 1 year.
liquidityAmm	int	gt, lt, eq	AMM liquidity.
liquidityClob	int	gt, lt, eq	CLOB liquidity.
enableNegRisk	bool	(direct value)	Negative risk enabled.
seriesSlug	str	partial, exact	Slug for the event series.
negRiskAugmented	bool	(direct value)	Negative risk augmented.

Response

• Status Code: 200 OK
  • Body: A JSON array of event objects that match the filter criteria.

    [
    {
        "id": 1,
        "title": "Test Event A",
        "category": "Sports",
        "volume24hr": 15000,
        "closed": false,
        "tags": ["football"],
        "markets": [
            {
                "slug": "test-market-a",
                "question": "Will A happen?"
            }
        ]
    }
    // ... matching event objects
    ]
    

• Status Code: 400 Bad Request
  • Body:

    {
    "error": "No filter parameters provided in request body."
    }
    

• Status Code: 500 Internal Server Error
  • Body:

    {
    "error": "An error occurred during filtering: [error message]"
    }
    

• Status Code: 503 Service Unavailable
  • Body:

    {
    "message": "Data not yet loaded. Please wait or check server logs."
    }
    

Example Usage (Python Requests)

import requests

filter_params = {
    "category_exact": "Sports",
    "volume24hr_gt": 10000,
    "closed": False,
    "title_partial": "Event"
}

try:
    response = requests.post(
        'http://api.polydataexplore.org/events/filter',
        json=filter_params 
    )
    response.raise_for_status() 
    data = response.json()
    print(data)
except requests.exceptions.RequestException as e:
    print(f"Error filtering events: {e}")
    if response.status_code:
        print(f"Status Code: {response.status_code}")
        print(f"Response Body: {response.text}")

---

3. Filter By ID

Filters the event data based on a list of IDs.

Endpoint

POST /events/filter_id

Description

This endpoint allows you to filter events based on a list of IDs.

Request

• Method: POST
• Content-Type: application/json
• Body: A JSON object with a key as "ids" and value as a list of ints.

Response

• Status Code: 200 OK
  • Body: A JSON array of event objects that match the filter criteria.

    [
    {
        "id": 24189,
        "title": "Example Event 1",
        "category": "Sports"
    },
    {
        "id": 23785,
        "title": "Example Event 2",
        "category": "Politics"
    }
    ]
    

• Status Code: 400 Bad Request
  • Body:

    {
    "error": "No filter parameters provided in request body."
    }
    

• Status Code: 500 Internal Server Error
  • Body:

    {
    "error": "An error occurred during filtering: [error message]"
    }
    

• Status Code: 503 Service Unavailable
  • Body:

    {
    "message": "Data not yet loaded. Please wait or check server logs."
    }
    

Example Usage (Python Requests)

import requests

try:
    response = requests.post(
        "http://api.polydataexplore.org/events/filter_id",
        json = {
            'ids' : [24189, 23785, 20823],
        },
        headers = {'Content-Type': 'application/json'}
    )
    response.raise_for_status() 
    data = response.json()
    print(data)
except requests.exceptions.RequestException as e:
    print(f"Error filtering events by ID: {e}")
    if response.status_code:
        print(f"Status Code: {response.status_code}")
        print(f"Response Body: {response.text}")

---

4. Get Price History By ID

Retrieves the price history for markets associated with a list of event IDs.

Endpoint

POST /price-history/filter_id

Description

This endpoint allows you to retrieve the historical price data for all markets within the events specified by a list of IDs. The response will be a dictionary where keys are event titles and values are lists of price data points for each market within that event.

Request

• Method: POST
• Content-Type: application/json
• Body: A JSON object with a key as "ids" and value as a list of integers, representing the event IDs.

Response

• Status Code: 200 OK
  • Body: A JSON object where keys are event titles and values are lists of market price data. Each market price data is a list of dictionaries, with each dictionary containing 't' (timestamp) and 'p' (price).

    {
    "Event Title 1": [
        {
            "t": 1678886400,
            "p": 0.55
        },
        {
            "t": 1678972800,
            "p": 0.58
        }
        // ... more price data points for this market
    ],
    "Event Title 2": [
        {
            "t": 1678886400,
            "p": 0.70
        },
        {
            "t": 1678972800,
            "p": 0.68
        }
        // ... more price data points for this market
    ]
    }
    

• Status Code: 400 Bad Request
  • Body:

    {
    "error": "No filter parameters provided in request body."
    }
    

• Status Code: 500 Internal Server Error
  • Body:

    {
    "error": "An error occurred during filtering: [error message]"
    }
    

• Status Code: 503 Service Unavailable
  • Body:

    {
    "message": "Data not yet loaded. Please wait or check server logs."
    }
    

Example Usage (Python Requests)

import requests

try:
    response = requests.post(
        "http://api.polydataexplore.org/price-history/filter_id",
        json = {
            'ids' : [24189, 23785], 
        },
        headers = {'Content-Type': 'application/json'}
    )
    response.raise_for_status() 
    data = response.json()
    print(data)
except requests.exceptions.RequestException as e:
    print(f"Error fetching price history: {e}")
    if response.status_code:
        print(f"Status Code: {response.status_code}")
        print(f"Response Body: {response.text}")