Quick Start

To use the Bilby Quant API, you will first need to sign up for an account, and that needs to be approved. After that, you can start using the API by making requests.

Create an API key here.

Example cURL Request

Make sure to replace <YOUR_API_KEY_HERE> with your actual API key.

curl -X 'POST' \
  'https://api.quant.bilby.ai/v1/documents' \
  -H 'accept: application/json' \
  -H 'x-api-key: <YOUR_API_KEY_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
  "dataset": "basic_documents",
  "start_date": "2024-09-27",
  "end_date": "2024-09-27",
  "offset": 0,
  "limit": 20000
}'

The API takes the following parameters:

dataset: The dataset from which you want to get data. Valid values are basic_documents, commodity_documents, and gics_documents.
start_date: The start date of the data range. The format is YYYY-MM-DD. The date is inclusive.
end_date: The end date of the data range. The format is YYYY-MM-DD. The date is inclusive.
offset: The offset of the data range. The default value is 0.
limit: The limit of the data range. The default value is 20000.

Note regarding offset and limit:

Offset means starting from the value of offset, and limit means the number of results to return. For example, if you set offset to 10 and limit to 10, you will get the 11th to 20th result.

Example Python Request

import requests

API_KEY = "<YOUR_API_KEY_HERE>"

response = requests.post(
    "https://api.quant.bilby.ai/v1/documents",
    headers={
        "accept": "application/json",
        "x-api-key": API_KEY,
    },
    json={
        "dataset": "basic_documents",
        "start_date": "2024-09-27",
        "end_date": "2024-09-27",
        "offset": 0,
        "limit": 10
    }
)

res = response.json()

# If you then want to use DataFrames, you can do the following:
import pandas as pd

df = pd.DataFrame(res["data"])

API Response Format

took is the milliseconds it took to process the request. stats includes two values,

hits: the number of results returned in data.
total: the total number of results in the date range. You can use this value to loop through the results.

data is an array of objects, each representing a document.

{
  "took": 145,
  "stats": { "hits": 2875, "total": 2875 },
  "data": [
    {
      "id": "b8e2baae6aea223d7ee4c1adbdd668c812181584ec8bdc8632cfce010168f771",
      "published_at": "2024-09-26T00:00:00.000Z",
      "utc_date": "2024-09-25T16:00:00.000Z",
      "source": "State-Owned Assets Supervision and Administration Commission",
      "source_line": "ministry",
      "source_country": "China",
      "source_language": "Chinese",
      "copies": 1,
      "copies_proportion": "0.0000",
      "sentiment_prediction": "positive",
      "positive_sentiment_probability": 0.634282291,
      "neutral_sentiment_probability": 0.357519478,
      "negative_sentiment_probability": 0.0000177088968,
      "sentiment_extremity": 0.40750263979577583,
      "sector_prediction": ["Utilities", "Energy"],
      "sector_probability_energy": 0.9854510380896018,
      "sector_probability_materials": 0.03835193681535576,
      "sector_probability_industrials": 0.7671805324238856,
      "sector_probability_consumer_discretionary": 0.10070077988032433,
      "sector_probability_consumer_staples": 0.016629152218752608,
      "sector_probability_health_care": 0.027707230409647843,
      "sector_probability_financials": 0.02547944232821009,
      "sector_probability_information_technology": 0.04352068946846133,
      "sector_probability_communication_services": 0.24500555014446856,
      "sector_probability_utilities": 0.9965082201653087,
      "sector_probability_real_estate": 0.09602526389032962,
      "sector_probability_macro": 0.5694763437047621,
      "sector_probability_not_relevant": 0.18607557101079852,
      "policy_stage_prediction": 0,
      "policy_stage_probability_0": 0.9965717792510986,
      "policy_stage_probability_1": 0.0020946061704307795,
      "policy_stage_probability_2": 0.0012986804358661175,
      "policy_stage_probability_3": 0.00003488860238576308,
      "importance_prediction": 1,
      "importance_probability_1": 0.874384344,
      "importance_probability_2": 0.0382087827,
      "importance_probability_3": 0.0845356882,
      "importance_probability_4": 0.0109673142,
      "importance_probability_5": 0.00554746389,
      "policy_impact_score": 0.2025008799319253,
      "policy_impact_percentage": 20.25008799319253
    },
    ...
  ]
}