OpenBB/website/content/platform/usage/basic_syntax.md

title, sidebar_position, description, keywords

title	sidebar_position	description	keywords
Basic Syntax	2	This page provides comprehensive information about standardized command syntax for an open-source platform. Topics discussed include the structure of command syntax, use of standardized parameters, usage of provider and symbol parameters, handling of date and limit parameters, and more. Also explored, are the methods for selecting data sources, handling different list and ticker symbol formats, and dealing with command responses and warnings.	command syntax standardized parameters date format provider parameter data source selection symbol parameter list formats ticker symbols date parameter time series limit parameter keyword arguments endpoint parameters command response data models

import HeadTitle from '@site/src/components/General/HeadTitle.tsx';

The structure of command syntax is standardized across common fields. This ensures that a date is always a date and the format remains consistent throughout. Standardized parameters include, but are not limited to:

• provider
• symbol
• start_date
• end_date
• date
• limit

When looking at a function's docstring, the standard parameters (shared across multiple providers) are positioned first. Provider-specific parameters positionally follow the provider argument. The example below is from, obb.equity.price.quote:

Parameters
----------
symbol : str
    Symbol to get data for. In this case, the comma separated list of symbols.
provider : Optional[Literal['fmp', 'intrinio']]
    The provider to use for the query, by default None.
    If None, the provider specified in defaults is selected or 'fmp' if there is
    no default.
source : Literal['iex', 'bats', 'bats_delayed', 'utp_delayed', 'cta_a_delayed', 'cta_b_delayed', 'intrinio_mx', 'intrinio_mx_plus', 'delayed_sip']
    Source of the data. (provider: intrinio)

:::note Examples below assume that the Python interface has been imported in the current session, and/or the Fast API has been started.

from openbb import obb

uvicorn openbb_core.api.rest_api:app

:::

Provider

The provider parameter is the way to select the specific source of the data from the endpoint. If a preference for the default provider has not been defined, the default will be the first, alphabetically, installed provider. Provider values are entered in lower-case, with an underscore for multiple words - for example:

historical_prices = obb.equity.price.historical("aapl", provider="alpha_vantage")

Provider coverage can be ascertained with the command below:

obb.coverage.providers

Refer to, Data Providers, for instructions on installing data provider extensions.

Symbol

Symbols are not case-sensitive, and where the function allows, can be entered as a string, List[str], or a comma-separated string. The exact format of the symbol may vary between providers - for example, share classes, exchange suffixes, and global composities. An example of this difference is shown below:

obb.equity.price.historical("brk.b", provider="polygon")

obb.equity.price.historical("brk-b", provider="fmp")

While some providers handle the different formats on their end, others do not. This is something to consider when no results are returned from one source.

With providers supporting market data from multiple jurisdictions, the most common method for requesting data outside of US-listings is to append a suffix to the ticker symbol (e.g., RELIANCE.NS). Formats may be unique to a provider, so it is best to review the source's documentation for an overview of their specific conventions. This page on Yahoo describes how they format symbols, which many others follow to some degree.

One Symbol

quote = obb.equity.price.quote(symbol="td", provider="fmp")

Multiple Symbols

The OpenBB Provider module enforces REST-compliant lists that can be entered in either format through the Python interface.

Comma-Separated String

This is the format required by the Fast API, when creating new data endpoints, it is important that the Python interface is able to accept both formats.

quotes = obb.equity.price.quote("td,schw,jpm,ms", provider="fmp")

import requests
r = requests.get("http://127.0.0.1:8000/api/v1/equity/price/quote?provider=fmp&symbol=td,schw,ms,jpm")
r.json()

Python List

Entering a list will provide the same outcome as above.

quotes = obb.equity.price.quote(["td","schw","jpm","ms"], provider="fmp")

Lists of symbols can be generated from the results of other functions, and then passed to the input.

symbol="spgi"
symbols = obb.equity.compare.peers(symbol).results.peers_list+[symbol]
quotes = obb.equity.price.quote(symbols)

:::note To accomplish this same task through the Fast API, convert the list to a comma-separated string. :::

import requests
symbol="spgi"
r = requests.get(f"http://127.0.0.1:8000/api/v1/equity/compare/peers?provider=fmp&symbol={symbol}")
symbols_list = r.json()["results"]["peers_list"]+[symbol]
symbols = ",".join(symbols_list)
response = requests.get(f"http://127.0.0.1:8000/api/v1/equity/price/quote?provider=fmp&symbol={symbols}")
response.json()

Dates

Dates are entered everywhere as a string, formatted as, "YYYY-MM-DD". If the function has only the date parameter, the data will be a snapshot instead of a time series.

historical_prices = obb.equity.price.historical(symbol="qqq", start_date="2023-01-10", end_date="2023-01-31", provider="fmp")

For flexibility and programmatic purposes, a datetime object is also accepted.

from datetime import datetime
symbol="qqq"
start = datetime.strptime("100123", "%d%m%y")
end = datetime.strptime("2023-01-31","%Y-%m-%d")
historical_prices = obb.equity.price.historical(symbol, start_date=start, end_date=end, provider="fmp")

import requests
response = requests.get(f"http://127.0.0.1:8000/api/v1/equity/price/historical?provider=fmp&symbol={symbol}&start_date={start}&end_date={end}")
response.json()

Limit

Where, optional, limit parameters are supplied, they are likely to have sensible default states that return N results starting from the most recent entry or the start_date. Enter these values as an integer.

income = obb.equity.fa.income("AAPL", period="quarter", provider="fmp", limit=4)

**kwargs

All endpoints accept additional keyword arguments, but non-existent parameters will be ignored. Invalid parameters are communicated via the warnings field in the command response. Parameters can be stored as a dictionary and fed to the command as **kwargs. If a provider, or function, has an undocumented parameter it can still be accessed by supplying the additional kwargs.

kwargs = {"symbol":"msft","start_date":"2023-01-01","provider":"polygon"}
historical_prices = obb.equity.price.historical(**kwargs)

data = obb.equity.price.quote("brk-b", provider="fmp", source="bats")
data.warnings

[Warning_(category='OpenBBWarning', message="Parameter 'source' is not supported by fmp. Available for: intrinio.")]

REST API POST Requests

Most endpoints are for data retrieval, but some toolkit extensions require data to pass through the function. In these instances, it must be a POST request, and JSON.

Example

This example will use a GET request to fetch daily VIX data from the Cboe data extension, and then make a POST request which passes through the data to a technical analysis function.

First, start a development server.

uvicorn openbb_core.api.rest_api:app --reload

This example will use Python and the Requests library, so the syntax will vary according to the preferred medium for interacting with the API.

Fetch Some Data

import requests

get_url = "http://127.0.0.1:8000/api/v1/index/market?provider=cboe&symbol=vix&interval=1d"
get_response = requests.get(get_url)
data_results = get_response.json()["results"]

data_results[-1]

{'date': '2023-11-17T00:00:00',
 'open': 14.18,
 'high': 14.19,
 'low': 13.67,
 'close': 13.79,
 'volume': 0,
 'calls_volume': None,
 'puts_volume': None,
 'total_options_volume': None}

Send a POST Request

Next, pass the data_results to a function, using the json field in the POST headers. For this example, realized volatiliy cones, the default parameters assume the time series data is daily and that volatility should be annualized over 252 trading days.

The index parameter tells the function which field in the posted data to use as the date index.

import pandas as pd

post_url = "http://localhost:8000/api/v1/technical/cones"
post_response = requests.post(post_url, json=data_results)
ta_results = post_response.json()["results"]

pd.DataFrame.from_records(ta_results)

window	realized	min	lower_25%	median	upper_75%	max
3	0.396165	0.00701638	0.444709	0.72414	1.11563	8.47636
10	0.623199	0.190188	0.665584	0.852915	1.15491	4.83264
30	0.988435	0.332913	0.750007	0.921482	1.17072	2.98404
60	0.932594	0.47639	0.792548	0.964617	1.20171	2.35563
90	0.915137	0.551011	0.815229	0.965553	1.2128	2.04104
120	0.858644	0.549233	0.836395	0.983437	1.21097	1.86416
150	0.898628	0.557274	0.842359	0.991539	1.23165	1.73182
180	0.902293	0.579575	0.84876	1.00421	1.23584	1.68786
210	0.901717	0.580214	0.854655	0.996992	1.2271	1.65739
240	0.884282	0.587564	0.857935	1.00491	1.22141	1.62973
300	0.852533	0.622105	0.862097	1.00724	1.21705	1.51887
360	0.847416	0.661648	0.869691	1.03923	1.20488	1.48571

References

All functions, parameters, and responses are detailed under the Reference pages. The data models for each provider source are described within the Data Models pages.

These pages are a quick way to cross-reference differences between providers. The same information is provided in a function's signature and docstring.