Skip to main content

Output Data

Python Interface​

OBBject​

The output of every command is an object which contains the results of the request, along with additional information. It is a custom class, OBBject, and always returns with the fields listed below:

id: ...                 # UUID Tag
results: ...            # Serializable results.
provider: ...           # Provider name.
warnings: ...           # List of warnings.
chart: ...              # Chart object.
extra: ...              # Extra info.
from openbb import obb

data = obb.equity.price.historical("SPY", provider="polygon")

data
OBBject

id: 06520558-d54a-7e53-8000-7aafc8a42694
results: [{'date': datetime.datetime(2022, 10, 5, 0, 0), 'open': 375.62, 'high': 37...
provider: polygon
warnings: None
chart: None
extra: {'metadata': {'arguments': {'provider_choices': {'provider': 'polygon'}, 'st...

Additional class methods are helpers for converting the results to a variety of formats.

  • to_dict(): converts to a dictionary, accepting all standard "orientation" parameters, i.e., "records"
  • to_df() / to_dataframe(): converts to a Pandas DataFrame.
  • to_numpy(): converts to a Numpy array.
  • to_polars(): converts to a Polars table.
info

The preferred output type can be set with a user preference.

obb.user.preferences.output_type="dataframe"

Metadata​

The OpenBB Platform returns metadata related to the command execution, as well as any returned from a Provider endpoint. Both are stored in the extra attribute of the OBBject response object.

It will always contain these elements:

  • arguments: Any parameters supplied, and the selected provider source, to the function.
  • duration: The number of nanoseconds the function took to complete.
  • route: The command path.
  • timestamp: Timestamp for when the command was run.

Execution Metadata​

Metadata for the command execution is captured under the metadata key.

from openbb import obb

data = obb.economy.calendar(provider="nasdaq")

data.extra
{'metadata': Metadata

 arguments: {'provider_choices': {'provider': 'nasdaq'}, 'standard_params': {'start_date': None, 'end_date': None}, 'extra_params': {}}
 duration: 565256375
 route: /economy/calendar
 timestamp: 2024-05-22 11:28:57.149548}

Disabling​

This content can be disabled as a setting in the user_settings.json file.

{
  "preferences": {
    "metadata": false
  }
}
note

Metadata included as part of the command results will not be disabled by this setting.

Results Metadata​

Where commands return metadata related to the requested data, it is keyable from the extra attribute with, results_metadata.

This dictionary contains contextual information and data for the results that is not included in the tables. Results metadata will vary by command and provider, so it is worth exploring when it is included, below is a selection of samples.

FRED
data = obb.economy.fred_series("T10Y2Y")

data.extra["results_metadata"]
{'T10Y2Y': {'title': '10-Year Treasury Constant Maturity Minus 2-Year Treasury Constant Maturity',
  'units': 'Percent',
  'frequency': 'Daily',
  'seasonal_adjustment': 'Not Seasonally Adjusted',
  'notes': 'Starting with the update on June 21, 2019, the Treasury bond data used in calculating interest rate spreads is obtained directly from the U.S. Treasury Department (https://www.treasury.gov/resource-center/data-chart-center/interest-rates/Pages/TextView.aspx?data=yield).\r\nSeries is calculated as the spread between 10-Year Treasury Constant Maturity (BC_10YEAR) and 2-Year Treasury Constant Maturity (BC_2YEAR). Both underlying series are published at the U.S. Treasury Department (https://www.treasury.gov/resource-center/data-chart-center/interest-rates/Pages/TextView.aspx?data=yield).'}}

The information stored here is used by the openbb-charting extension for display.

FRED Chart

EconDB
data = obb.economy.indicators("PCOPP", provider="econdb")

data.extra
{'results_metadata': {'PCOPP': {'title': 'World - Copper',
   'country': 'World',
   'frequency': 'M',
   'dataset': 'IMF_PCPS',
   'transform': None,
   'units': 'USD',
   'scale': 'Units',
   'multiplier': 1,
   'additional_info': {'FREQ:Frequency': 'M:Monthly',
    'REF_AREA:Reference Area': 'W00:All Countries, excluding the IO',
    'COMMODITY:Commodity': 'PCOPP:Primary Commodity Prices, Copper',
    'UNIT_MEASURE:Unit of Measure': 'USD:US Dollars',
    'UNIT_MULT:Scale': '0:Units'}}},
}
Cboe
data = obb.derivatives.options.chains("SPX", provider="cboe")

data.extra
{'results_metadata': {'symbol': '^SPX',
  'security_type': 'index',
  'bid': 5293.0298,
  'bid_size': 1,
  'ask': 5295.2002,
  'ask_size': 1,
  'open': 5319.2798,
  'high': 5323.1802,
  'low': 5286.0098,
  'close': 5294.0898,
  'volume': 0,
  'current_price': 5294.0898,
  'prev_close': 5321.4102,
  'change': -27.3202,
  'change_percent': None,
  'iv30': 10.291,
  'iv30_change': 0.546,
  'iv30_change_percent': 0.056029,
  'last_tick': 'down',
  'last_trade_timestamp': '2024-05-22 14:50:36'},
}
SEC
data = obb.etf.holdings("BIL", provider="sec")

data.extra
{'results_metadata': {'fund_name': 'SPDR(R) Bloomberg 1-3 Month T-Bill ETF',
  'series_id': 'S000017326',
  'lei': '549300GQCVCME1YJ6B50',
  'period_ending': '2023-12-31',
  'fiscal_year_end': '2024-06-30',
  'total_assets': 35015168619.91,
  'total_liabilities': 1638123692.3,
  'net_assets': 33377044927.61,
  'cash_and_equivalents': '0.00000000',
  'returns': {'2023-10-31': 0.0044,
   '2023-11-30': 0.0044,
   '2023-12-31': 0.0046},
  'flow': {'2023-10-31': {'creation': 6591274706.7,
    'redemption': 604472521.85},
   '2023-11-30': {'creation': 3244045301.3, 'redemption': 4478684406.9},
   '2023-12-31': {'creation': 639802303.2, 'redemption': 3018629744.0}},
  'gains': {'2023-10-31': {'realized': -65924.99, 'unrealized': -3793500.04},
   '2023-11-30': {'realized': 360345.39, 'unrealized': 292210.09},
   '2023-12-31': {'realized': 319796.93, 'unrealized': 3862704.46}},
  'borrowers': [{'name': 'BofA Securities, Inc.',
    'lei': '549300HN4UKV1E2R3U73',
    'value': 211562959.29},
   {'name': 'J.P. Morgan Securities LLC',
    'lei': 'ZBUT11V806EZRVTWT807',
    'value': 957576952.9},
   {'name': 'ING Financial Markets LLC',
    'lei': 'KBVRJ5K57JZ3E2AVWX40',
    'value': 247944722.5},
   {'name': 'Barclays Capital Inc.',
    'lei': 'AC28XWWI3WIBK2824319',
    'value': 248250000.0},
   {'name': 'Goldman Sachs & Co. LLC',
    'lei': 'FOR8UP27PHTHYVLBNG30',
    'value': 110741598.05},
   {'name': 'Bank of Montreal',
    'lei': 'NQQ6HPCNCCU6TUTQYE16',
    'value': 87276542.32},
   {'name': 'Nomura Securities International, Inc.',
    'lei': 'OXTKY6Q8X53C9ILVV871',
    'value': 469556172.09},
   {'name': 'Daiwa Capital Markets America Inc.',
    'lei': 'M67H5PRC0NQKM73ZAS82',
    'value': 198566750.0}]}
}

LLM friendly mode​

The OpenBB Platform provides a way to enable the Large Language Model (LLM) mode, which allows you to use LLM frameworks such as Magentic, Langchain, Haystack, and more.

This guide outlines the steps to enable LLM mode in the OpenBB Platform.

We first start by importing the OpenBB Platform:

from openbb import obb

The LLM mode is made possible by setting the system and user preferences to an LLM-compatible mode.

First, we set the user preference:

obb.user.preferences.output_type="llm"

This line of code converts the OBBject response data results into a format that works good with LLM models. This is based on our own experience with building LLM agents for financial data. You can try other output types such as dict, or similar. You can also build your custom output type.

Next, we set the system preferences:

obb.system.python_settings.docstring_sections=['description', 'examples']

This system preference trims the docstrings of the commands so that they can fit into the LLM model's context size and also avoid redundant information. The redundant information comes from the information inside the signature of the command that is also written in the docstring.

As our docstrings are modular we can easily choose which section of the docstrings to include. Available docstring sections are the following:

  • description
  • parameters
  • returns
  • examples

The next step is to limit the size of the docstrings:

obb.system.python_settings.docstring_max_length=1024

We do this to ensure that the docstrings are not too long for the LLM model to process. The LLM model has a limit on the number of tokens it can process at once, and this setting ensures that the docstrings are within that limit.

Finally, we can import openbb and rebuild the Python static assets to apply these system changes:

import openbb
openbb.build()

Now you have successfully enabled LLM mode in the OpenBB Platform. You can now use LLM frameworks to interact with the OpenBB Platform and build financial agents that can understand and respond to financial data.

For example:

from magentic import prompt_chain, FunctionCall, OpenaiChatModel

@prompt_chain(
    "You are a helpful financial agent that can use function calling to retrieve data.\nUser Query: {query}",
    functions=[obb.equity.price.quote],
    model=OpenaiChatModel(model="gpt-4-turbo-preview")
)
def llm(query: str) -> FunctionCall | str: ...

r = llm(query="What is the current stock price of AAPL?")
r

REST API​

The OpenBB Platform comes with a FastAPI application that serves platform commands as REST API endpoints.

Activate the Python environment and then start the server from a Terminal command line with:

uvicorn openbb_core.api.rest_api:app
info

See System Settings for details on configuring settings in system_settings.json

You can add arguments that are supported by uvicorn to customize how the API is launched. For example this command will be useful if you are developing. It will launch the API in a way it's reachable on your local network and reload every time the code changes:

uvicorn openbb_core.api.rest_api:app --host 0.0.0.0 --port 8000 --reload

To learn more about how you can run the API in different scenarios refer to uvicorn's documentation

API Documentation​

The Fast API app comes with a swagger documentation page. When running the API locally, navigate to http://127.0.0.1:8000/docs.

The API Docs provide interactive descriptions of all available endpoints that you can call right from the documentation web page.

Data API Keys​

The API keys to your data providers are loaded from the ~/.openbb_platform/user_settings.json file.

You can find more information about the structure of the file and environment variables in the Local Environment section.

API Authorization​

By default, no authorization is required. Basic authorization can be enabled with environment variables. In the ~/.openbb_platform folder, next to the user_settings.json, create a new file, .env, if it does not yet exist. Set your Basic Auth credentials.

OPENBB_API_AUTH="True"
OPENBB_API_USERNAME="my_email"
OPENBB_API_PASSWORD="my_password"

The application will expect a header that contains username and password in the form of Basic <username:password>, where "username:password" is encoded in Base64. Pass this in every request to the API inside the headers "Authorization" field.

Here is an example of calling the API that has Basic Authorization enabled from python.

import base64
import requests

msg = "some_user:some_pass"
msg_bytes = msg.encode('ascii')
base64_bytes = base64.b64encode(msg_bytes)
base64_msg = base64_bytes.decode('ascii')


symbol="SPY"
url = f"http://127.0.0.1:8000/api/v1/equity/price/quote?provider=intrinio&symbol={symbol}&source=intrinio_mx"
headers = {"accept": "application/json", "Authorization": f"Basic {base64_msg}"}

response = requests.get(url=url, headers=headers)

response.json()

Advanced API Settings​

info

See System Settings for details on configuring settings in system_settings.json

When deploying the API to the public internet, it's crucial to configure it in a way you ensure the application functions correctly and securely. Two critical aspects to consider are Cross-Origin Resource Sharing (CORS) and the configuration of the "servers" list.

The configuration for these settings is managed through the system_settings.json file, which should be located in the same directory as your user_settings.json. This JSON file allows you to specify various settings that affect the behavior of the API. Here's an example structure of the system_settings.json file:

{
  "api_settings": {
    "version": "1",
    "title": "OpenBB Platform API",
    "description": "This is the OpenBB Platform API.",
    "terms_of_service": "http://example.com/terms/",
    "contact_name": "OpenBB Team",
    "contact_url": "https://openbb.co",
    "contact_email": "hello@openbb.co",
    "license_name": "AGPLv3",
    "license_url": "https://github.com/OpenBB-finance/OpenBB/blob/develop/LICENSE",
    "servers": [
      {
        "url": "",
        "description": "Local OpenBB development server"
      }
    ],
    "cors": {
      "allow_origins": ["*"],
      "allow_methods": ["*"],
      "allow_headers": ["*"]
    },
    "prefix": "/api/v1"
  }
}

CORS Configuration​

The cors section within the api_settings is particularly important for web applications. It defines the rules for which external domains are allowed to access your API.

In the example above, the settings are permissive ("*" for origins, methods, and headers), which means any external domain can request resources from your API. This setting might be suitable for development, but when deploying to public internet, you should specify the exact domains, methods, and headers to tighten security.

Servers List​

The servers array is used to specify the different environments where your API can be accessed.

In the example, there is only one server defined, which is the local development server. For deployment to public internet, you would add an entry for the public server URL and any other environments where your API is accessible.

On this page