get_series_exp Function

get_series_exp Function#

The get_series_exp function fetches economic data series from a specified API and returns it formatted as a pandas DataFrame. This function offers various parameters to fine-tune the data retrieval process.

evdspy.get_series_exp(index: str | tuple[Any, ...], start_date: str = '01-01-2000', end_date: str = '01-01-2100', frequency: Literal['monthly', 'weekly', 'annually', 'semimonthly', 'semiannually', 'business', None] = None, formulas: Literal['level', 'percentage_change', 'difference'] | None = None, aggregation: Literal['avg', 'min', 'max', 'first', 'last', 'sum', None] | None = None, cache: bool = False, meta_cache: bool = False, proxy: str | None = None, proxies: dict[str, str] | None = None, debug: bool = False, api_key: str | None = None) → Result[source]#

Retrieves economic data series from the specified API and returns it as a pandas DataFrame. Parameters ———- index : str or tuple of str

The identifier(s) for the data series to fetch. Can be a single string for one series or a tuple of strings for multiple series.

start_datestr, optional

The start date for the data retrieval in ‘DD-MM-YYYY’ format, by default calls default_start_date_fnc().

end_datestr, optional

The end date for the data retrieval in ‘DD-MM-YYYY’ format, by default calls default_end_date_fnc().

frequencystr, optional

The frequency at which data should be retrieved. monthly | weekly | annually | semimonthly | semiannually | business

formulasstr or tuple of str, optional

The computation methods to apply to the data series level | percentage_change | difference | year_to_year_percent_change | year_to_year_differences

aggregationstr or tuple of str, optional

The aggregation methods to apply to the data, similar to formulas. avg |min | max | first | last | sum

cachebool, optional

If True, uses cached data when available to speed up the data retrieval process, by default False.

meta_cachebool, optional

If True, uses cached data for metadata when available to speed up the data retrieval process, by default False.

proxystr, optional

The URL of the proxy server to use for the requests, by default None.

proxiesdict, optional

A dictionary of proxies to use for the request, by default None.

debugbool, optional

If True, runs the function in debug mode, providing additional debug information without making a real API request, by default False.

api_keystr, optional

The API key required for accessing the data, by default None. When it was given for the first time it will be saved to a file for the subsequent requests. alternatively it may be saved by save(“APIKEY”) function or $ evdspy save [from console]

Returns#

pd.DataFrame

A pandas DataFrame containing the retrieved data series.

Raises#

ValueError

If an invalid API key is provided or required parameters are missing.

Parameters#

indexstr or tuple

Identifier(s) for the data series to fetch. This can be a single string for one series or a tuple of strings for multiple series.

start_datestr, optional

The start date for the data retrieval in ‘DD-MM-YYYY’ format. By default, this calls default_start_date_fnc().

end_datestr, optional

The end date for the data retrieval in ‘DD-MM-YYYY’ format. By default, this calls default_end_date_fnc().

frequencystr, optional

The frequency at which data should be retrieved. Options include:

  • daily (1): Data retrieved every day.

  • business (2): Data retrieved only on business days.

  • weekly (3): Data retrieved weekly on Fridays.

  • semimonthly (4): Data retrieved twice a month.

  • monthly (5): Data retrieved once a month.

  • quarterly (6): Data retrieved every quarter.

  • semiannually (7): Data retrieved twice a year.

  • annual/annually (8): Data retrieved once a year.

formulasstr or tuple, optional

Computation methods to apply to the data series. Options include:

  • level (0): Raw data values.

  • percentage change (1): Percent change between consecutive data points.

  • difference (2): Difference between consecutive data points.

  • year to year percent change (3): Percent change from the same date in the previous year.

  • year to year differences (4): Difference from the same date in the previous year.

  • percentage change compared to end-of-previous year (5): Percent change relative to the end of the previous year.

  • difference compared to end-of-previous year (6): Difference relative to the end of the previous year.

  • moving average (7): Moving average of data points.

  • moving sum (8): Moving sum of data points.

aggregationstr or tuple, optional

Aggregation methods to apply to the data. Options include:

  • avg: Average value over the specified period.

  • min: Minimum value over the specified period.

  • max: Maximum value over the specified period.

  • first: First value within the specified period.

  • last: Last value within the specified period.

  • sum: Sum of all values within the specified period.

cachebool, optional

If True, uses cached data when available to speed up the data retrieval process. Default is False.

meta_cachebool, optional

If True, uses cached metadata when available to speed up the data retrieval process. Default is False.

proxystr, optional

The URL of the proxy server to use for the requests. Default is None.

proxiesdict, optional

A dictionary of proxies to use for the request. Default is None.

debugbool, optional

If True, runs the function in debug mode, providing additional debug information without making a real API request. Default is False.

api_keystr, optional

The API key required for accessing the data. Initially, it can be saved using the save("APIKEY") function or via command line with $ evdspy save.

Returns#

Result Class

An object containing the following attributes:

datapd.DataFrame

The retrieved data series.

metadatapd.DataFrame

Metadata associated with the data series, if available.

writeCallable

Function to create an Excel file with data and metadata in two sheets.

to_excelCallable

Same as write, for compatibility with pandas’ to_excel function.

Raises#

ValueError

Raised if an invalid API key is provided or required parameters are missing.

Creating a .env File#

Create a .env file in the root directory of your project and define your proxies as shown below:

# Example .env file content
EVDS_API_KEY=AxByCzDsFoGmHeIgJaKrLbMaNgOe

Examples#

Basic usage:

from evdspy import get_series_exp

template = """

TP.KREDI.L002
TP.BFTUKKRE.L004
TP.BFTUKKRE.L056
TP.BFTUKKRE.L193
TP.BFTUKKRE.L234
"""

result = get_series_exp(index, start_date="01-01-2020", end_date="01-01-2021", frequency="monthly")
print(result.data.head())
print(result.metadata)
result.write('output1.xlsx')
result.to_excel('output2.xlsx')

Using multiple indexes and cache:

from evdspy import get_series_exp

indexes = ("TP.ENFBEK.PKA12ENF", "TP.ENFBEK.IYA12ENF")
result = get_series_exp(indexes, start_date="01-01-2020", end_date="01-01-2021", frequency="monthly")
print(result.data.head())
print(result.metadata)
result.write('output1.xlsx')
result.to_excel('output2.xlsx')

Applying formulas and aggregation:

from evdspy import get_series_exp

template = """

TP.KREDI.L002
TP.BFTUKKRE.L004
TP.BFTUKKRE.L056
TP.BFTUKKRE.L193
TP.BFTUKKRE.L234
"""

result = get_series_exp(template, formulas="level", aggregation="sum")
print(result.data.head())
print(result.metadata)
result.write('output.xlsx')
result.to_excel('output2.xlsx')