### Install ipeadatapy

Source: https://github.com/luanborelli/ipeadatapy/blob/master/docs/source/usage/installation/pip.rst

Use this command to install the ipeadatapy library from PyPI.

```bash
pip install ipeadatapy
```

--------------------------------

### Upgrade ipeadatapy

Source: https://github.com/luanborelli/ipeadatapy/blob/master/docs/source/usage/installation/pip.rst

Run this command to ensure you have the latest version of ipeadatapy installed.

```bash
pip install --upgrade ipeadatapy
```

--------------------------------

### GET /sources

Source: https://github.com/luanborelli/ipeadatapy/blob/master/docs/source/usage/quickstart/metadata.rst

Retrieves a list of all data sources available in the Ipeadata system.

```APIDOC
## GET /sources

### Description
Returns a list of all data sources.

### Method
GET

### Endpoint
ipeadatapy.sources()

### Response
#### Success Response (200)
- **Source** (string) - Name of the data source
```

--------------------------------

### GET /sources

Source: https://github.com/luanborelli/ipeadatapy/blob/master/docs/source/usage/functions/sources.rst

Retrieves a list of all available Ipeadata sources formatted as a data frame.

```APIDOC
## GET /sources

### Description
Returns available Ipeadata's sources in the form of a data frame.

### Method
GET

### Endpoint
sources()

### Response
#### Success Response (200)
- **data** (DataFrame) - A data frame containing the list of available Ipeadata sources.
```

--------------------------------

### GET /themes

Source: https://github.com/luanborelli/ipeadatapy/blob/master/docs/source/usage/functions/themes.rst

Retrieves a list of available Ipeadata themes with optional filtering parameters.

```APIDOC
## GET /themes

### Description
Returns a pandas DataFrame containing available Ipeadata themes. The results can be filtered by specific attributes.

### Method
GET

### Endpoint
/themes

### Parameters
#### Query Parameters
- **theme_id** (int) - Optional - Theme ID by which the return will be filtered
- **name** (str) - Optional - Theme name by which the return will be filtered
- **macro** (int) - Optional - If 1, returns only themes related to the Macroeconomics big theme
- **regional** (int) - Optional - If 1, returns only themes related to the Regional big theme
- **social** (int) - Optional - If 1, returns only themes related to the Social big theme

### Response
#### Success Response (200)
- **data** (pandas.DataFrame) - Returns available Ipeadata themes
```

--------------------------------

### GET /countries

Source: https://github.com/luanborelli/ipeadatapy/blob/master/docs/source/usage/quickstart/metadata.rst

Retrieves a list of all available countries in the Ipeadata database.

```APIDOC
## GET /countries

### Description
Returns a list of available countries and their corresponding IDs.

### Method
GET

### Endpoint
ipeadatapy.countries()

### Response
#### Success Response (200)
- **ID** (string) - Unique identifier for the country
- **COUNTRY** (string) - Name of the country
```

--------------------------------

### GET /territories

Source: https://github.com/luanborelli/ipeadatapy/blob/master/docs/source/usage/functions/territories.rst

Retrieves a list of territories with optional filtering parameters.

```APIDOC
## GET /territories

### Description
Retrieves a list of territories with optional filtering parameters.

### Method
GET

### Endpoint
/territories

### Parameters
#### Query Parameters
- **name** (str, optional) - Territory name by which the return will be filtered.
- **level** (str, optional) - Territory level by which the return will be filtered.
- **territory_id** (str, optional) - Territory ID by which the return will be filtered.
- **area** (float, optional) - Territorial area by which the return will be filtered.
- **areaGreaterThan** (float, optional) - Territorial area restriction by which the return will be filtered. The function will return only territories with area strictly greater than the submitted value.
- **areaSmallerThan** (float, optional) - Territorial area restriction by which the return will be filtered. The function will return only territories with area strictly smaller than the submitted value.
- **capital** (bool, optional) - Return only capitals? True or False.

### Response
#### Success Response (200)
- **pandasDataframe** - Returns available Ipeadata territories.
```

--------------------------------

### Perform Custom API Call

Source: https://github.com/luanborelli/ipeadatapy/blob/master/notebooks/Ipeadatapy Usage Demonstration.ipynb

Executes a direct GET request to a specified Ipeadata API endpoint.

```python
idpy.api_call("http://ipeadata2-homologa.ipea.gov.br/api/v1/Paises")
```

--------------------------------

### Get Time Series Data for a Specific Day, Month, and Year

Source: https://github.com/luanborelli/ipeadatapy/blob/master/docs/source/usage/quickstart/basics.rst

Use 'year', 'month', and 'day' parameters to pinpoint data for a single day. This provides the most granular time series data retrieval.

```python
>>> ipeadatapy.timeseries("GM366_ERC366", year=2019, month=4, day=1)
       YEAR  DAY  MONTH          CODE                       DATE  VALUE (R$)
12139  2019    1      4  GM366_ERC366  2019-04-01T00:00:00-03:00      3.8676
```

--------------------------------

### GET /territories

Source: https://github.com/luanborelli/ipeadatapy/blob/master/docs/source/usage/quickstart/metadata.rst

Retrieves information about Brazilian territories.

```APIDOC
## GET /territories

### Description
Returns information regarding Brazilian territories for regional time series.

### Method
GET

### Endpoint
ipeadatapy.territories()

### Response
#### Success Response (200)
- **NAME** (string) - Name of the territory
- **ID** (string) - Unique identifier
- **AREA** (float) - Area information
- **CAPITAL** (string) - Capital city
```

--------------------------------

### Retrieve Series Details

Source: https://github.com/luanborelli/ipeadatapy/blob/master/docs/source/usage/quickstart/basics.rst

Get summary information or full metadata for a specific time series using its code.

```python
ipeadatapy.describe('BPAG_AR')
```

```python
ipeadatapy.metadata('BPAG_AR')
```

--------------------------------

### GET countries()

Source: https://github.com/luanborelli/ipeadatapy/blob/master/docs/source/usage/functions/countries.rst

Retrieves a list of all available countries and their IDs in a data frame format.

```APIDOC
## GET countries()

### Description
Returns all available Ipeadata's countries and country IDs in the form of a data frame.

### Method
GET

### Endpoint
countries()

### Response
#### Success Response (200)
- **data frame** (object) - A data frame containing country names and their associated IDs.
```

--------------------------------

### Describe a Time Series

Source: https://context7.com/luanborelli/ipeadatapy/llms.txt

Get a formatted summary of a single time series' key metadata attributes. Useful for understanding a series before retrieving its data.

```python
import ipeadatapy as ipea

# Get detailed description of a time series
description = ipea.describe("BM12_PIB12")
print(description)
# Output:
#                              Produto interno bruto (PIB)...
# Name                         Produto interno bruto (PIB)...
# Code                         BM12_PIB12
# Big Theme                    Macroeconômico
# Theme code                   4
# Source                       Banco Central do Brasil
# Source acronym               BCB
# Comment                      ...
# Last update                  2024-01-15T...
# Frequency                    Mensal
# Measure                      R$ (milhões)
# Unit                         Índice
# Status                       A

# Describe an inflation series
inflation_desc = ipea.describe("PRECOS12_IPCA12")
print(inflation_desc)
```

--------------------------------

### Get Time Series Data for a Specific Month and Year

Source: https://github.com/luanborelli/ipeadatapy/blob/master/docs/source/usage/quickstart/basics.rst

Combine 'year' and 'month' parameters to filter data for a specific month within a given year. This is useful for monthly analysis.

```python
>>> ipeadatapy.timeseries("GM366_ERC366", year=2019, month=4)
       YEAR  DAY  MONTH          CODE                       DATE  VALUE (R$)
12139  2019    1      4  GM366_ERC366  2019-04-01T00:00:00-03:00      3.8676
12140  2019    2      4  GM366_ERC366  2019-04-02T00:00:00-03:00      3.8655
12141  2019    3      4  GM366_ERC366  2019-04-03T00:00:00-03:00      3.8430
12142  2019    4      4  GM366_ERC366  2019-04-04T00:00:00-03:00      3.8707
12143  2019    5      4  GM366_ERC366  2019-04-05T00:00:00-03:00      3.8616
12144  2019    8      4  GM366_ERC366  2019-04-08T00:00:00-03:00      3.8652
12145  2019    9      4  GM366_ERC366  2019-04-09T00:00:00-03:00      3.8557
12146  2019   10      4  GM366_ERC366  2019-04-10T00:00:00-03:00      3.8339
...     ...  ...    ...           ...                        ...         ...

```

--------------------------------

### GET api_call

Source: https://github.com/luanborelli/ipeadatapy/blob/master/docs/source/usage/functions/api_call.rst

Retrieves raw data from the Ipeadata API and returns it as a data frame.

```APIDOC
## GET api_call

### Description
For advanced users. Returns raw Ipeadata API data in the form of a data frame.

### Parameters
#### Path Parameters
- **api** (str) - Required - The API endpoint string to query from Ipeadata.
```

--------------------------------

### Get Time Series Data for a Specific Year

Source: https://github.com/luanborelli/ipeadatapy/blob/master/docs/source/usage/quickstart/basics.rst

Use the 'year' parameter to retrieve all data points for a particular year. This is useful for analyzing yearly trends.

```python
>>> ipeadatapy.timeseries("GM366_ERC366", year=2019)
       YEAR  DAY  MONTH          CODE                       DATE  VALUE (R$)
12078  2019    2      1  GM366_ERC366  2019-01-02T00:00:00-02:00      3.8589
12079  2019    3      1  GM366_ERC366  2019-01-03T00:00:00-02:00      3.7677
12080  2019    4      1  GM366_ERC366  2019-01-04T00:00:00-02:00      3.7621
12081  2019    7      1  GM366_ERC366  2019-01-07T00:00:00-02:00      3.7056
12082  2019    8      1  GM366_ERC366  2019-01-08T00:00:00-02:00      3.7202
12083  2019    9      1  GM366_ERC366  2019-01-09T00:00:00-02:00      3.6925
12084  2019   10      1  GM366_ERC366  2019-01-10T00:00:00-02:00      3.6863
12085  2019   11      1  GM366_ERC366  2019-01-11T00:00:00-02:00      3.7135
12086  2019   14      1  GM366_ERC366  2019-01-14T00:00:00-02:00      3.7255
12087  2019   15      1  GM366_ERC366  2019-01-15T00:00:00-02:00      3.7043
...     ...  ...    ...           ...                        ...         ...
[89 rows x 6 columns]
```

--------------------------------

### List All Available Countries

Source: https://context7.com/luanborelli/ipeadatapy/llms.txt

Retrieve all countries with data in Ipeadata, providing country codes for filtering international data series. Includes examples of searching by keyword and specific ID.

```python
import ipeadatapy as ipea

# Get all available countries
all_countries = ipea.countries()
print(f"Total countries: {len(all_countries)}")
print(all_countries.head(20))
# Output:
#       ID              COUNTRY
# 0    AFG           Afeganistão
# 1    ZAF        África do Sul
# 2    DEU             Alemanha
# ...

# Search for countries by keyword
south_american = ipea.countries(keyword="Brasil")
print(south_american)

# Get country by specific ID
brazil = ipea.countries(country_id="BRA")
print(brazil)

# Use country code to filter metadata
usa_series = ipea.metadata(country="USA")
print(f"USA series: {len(usa_series)}")
```

--------------------------------

### GET /timeseries

Source: https://github.com/luanborelli/ipeadatapy/blob/master/notebooks/Ipeadatapy Usage Demonstration.ipynb

Retrieves time series data based on a series code and optional temporal filters.

```APIDOC
## GET /timeseries

### Description
Returns the specified time series' data values based on the provided series code and optional filters.

### Method
GET

### Endpoint
/timeseries

### Parameters
#### Query Parameters
- **series** (str) - Required - Time series code.
- **groupby** (str) - Optional - Grouping criteria.
- **year** (int) - Optional - Restrict data to a specific year.
- **yearGreaterThan** (int) - Optional - Restrict to years strictly greater than the value.
- **yearSmallerThan** (int) - Optional - Restrict to years strictly smaller than the value.
- **day** (int) - Optional - Restrict data to a specific day.
- **dayGreaterThan** (int) - Optional - Restrict to days strictly greater than the value.
- **daySmallerThan** (int) - Optional - Restrict to days strictly smaller than the value.
- **month** (int) - Optional - Restrict data to a specific month.
- **monthGreaterThan** (int) - Optional - Restrict to months strictly greater than the value.
- **monthSmallerThan** (int) - Optional - Restrict to months strictly smaller than the value.
- **code** (str) - Optional - Time series code restriction.
- **date** (str) - Optional - Specific date restriction.

### Response
#### Success Response (200)
- **data** (object) - Returns the data series for the specified time series.
```

--------------------------------

### GET metadata

Source: https://github.com/luanborelli/ipeadatapy/blob/master/docs/source/usage/functions/metadata.rst

Retrieves metadata for time series based on optional filtering parameters.

```APIDOC
## GET metadata

### Description
Retrieves metadata for time series. Users can filter the results by providing specific criteria such as series code, theme, source, or frequency.

### Method
GET

### Parameters
#### Query Parameters
- **series** (str) - Optional - Time series code. For the available time series run list_series().
- **big_theme** (str) - Optional - Big theme by which the return will be filtered. Options: "Macroeconômico", "Regional" or "Social".
- **source** (str) - Optional - Source by which the return will be filtered. For available sources run sources() function.
- **country** (str) - Optional - Country ID by which the return will be filtered. For available countries and their IDs run countries() function.
- **frequency** (str) - Optional - Frequency by which the return will be filtered.
- **unit** (str) - Optional - Unit by which the return will be filtered.
- **measure** (str) - Optional - Measure by which the return will be filtered.
- **status** (str) - Optional - Status by which the return will be filtered. Available options: "A" and "I".
```

--------------------------------

### List All Available Time Series - Python

Source: https://context7.com/luanborelli/ipeadatapy/llms.txt

Use `list_series` to get a DataFrame of all available time series. This function can be filtered by keyword, exact code, or exact name.

```python
import ipeadatapy as ipea

# List all available time series
all_series = ipea.list_series()
print(f"Total series available: {len(all_series)}")
print(all_series.head())
```

```python
# Search for time series containing a keyword
gdp_series = ipea.list_series(keyword="PIB")
print(f"GDP-related series: {len(gdp_series)}")
print(gdp_series[['CODE', 'NAME']].head(10))
```

```python
# Get specific series by exact code
specific_series = ipea.list_series(code="BM12_PIB12")
print(specific_series)
```

--------------------------------

### Retrieve All Time Series with Metadata

Source: https://github.com/luanborelli/ipeadatapy/blob/master/docs/source/usage/quickstart/advanced_filtering.rst

Use the metadata() function to get a comprehensive DataFrame of all available time series, including their metadata. This is useful for exploring the full dataset or for advanced filtering.

```python
ipeadatapy.metadata()
```

--------------------------------

### Get All Time Series with Metadata

Source: https://github.com/luanborelli/ipeadatapy/blob/master/notebooks/Ipeadatapy Usage Demonstration.ipynb

Use the `metadata()` function to retrieve a DataFrame containing all available time series and their associated metadata. This function provides more detailed information than `list_series()`.

```python
idpy.metadata()
```

--------------------------------

### Retrieve Time Series Metadata - Python

Source: https://context7.com/luanborelli/ipeadatapy/llms.txt

Use the `metadata` function to get detailed information about time series. It allows filtering by various attributes like theme, source, frequency, and country.

```python
import ipeadatapy as ipea

# Get metadata for a specific time series
gdp_meta = ipea.metadata("BM12_PIB12")
print(gdp_meta[['NAME', 'SOURCE', 'FREQUENCY', 'MEASURE', 'LAST UPDATE']])
# Output:
#                                   NAME          SOURCE FREQUENCY    MEASURE       LAST UPDATE
# 0  Produto interno bruto (PIB) - ...   Banco Central   Mensal      R$ ...    2024-01-15...

```

```python
# Get all metadata with filtering by big theme
macro_series = ipea.metadata(big_theme="Macroeconômico")
print(f"Macroeconomic series: {len(macro_series)}")
```

```python
# Filter by data source acronym
bcb_series = ipea.metadata(source="BCB")
print(f"Central Bank series: {len(bcb_series)}")
```

```python
# Filter by frequency
monthly_series = ipea.metadata(frequency="Mensal")
print(f"Monthly series: {len(monthly_series)}")
```

```python
# Filter by country
brazil_series = ipea.metadata(country="BRA")
print(f"Brazil series: {len(brazil_series)}")
```

```python
# Combine multiple filters
filtered = ipea.metadata(big_theme="Macroeconômico", source="BCB", frequency="Mensal")
print(f"Monthly BCB Macro series: {len(filtered)}")
```

--------------------------------

### Get Time Series Data

Source: https://github.com/luanborelli/ipeadatapy/blob/master/docs/source/usage/functions/timeseries.rst

Retrieve time series data with optional filters for month, code, and date.

```APIDOC
## GET /timeseries

### Description
Retrieves time series data from the IpeaData API with specified filters.

### Method
GET

### Endpoint
/timeseries

### Query Parameters
- **month** (int, optional) - Filters the data set to a specific month.
- **monthGreaterThan** (int, optional) - Filters the data set to months strictly greater than the specified month.
- **monthSmallerThan** (int, optional) - Filters the data set to months strictly smaller than the specified month.
- **code** (str, optional) - Filters the data set to a specific time series code.
- **date** (str, optional) - Filters the data set to a specific date.

### Response
#### Success Response (200)
- **return** (pandas.DataFrame) - Returns the data series for the specified time series.

#### Response Example
```json
{
  "example": "pandas.DataFrame output"
}
```
```

--------------------------------

### Get Time Series Data for Years Greater Than a Specific Year

Source: https://github.com/luanborelli/ipeadatapy/blob/master/docs/source/usage/quickstart/basics.rst

Utilize the 'yearGreaterThan' parameter to fetch data only from years that are strictly after the specified year. This is useful for trend analysis over recent periods.

```python
>>> ipeadatapy.timeseries("GM366_ERC366", yearGreaterThan=2017)
       YEAR  DAY  MONTH          CODE                       DATE  VALUE (R$)
11828  2018    2      1  GM366_ERC366  2018-01-02T00:00:00-02:00      3.2691
11829  2018    3      1  GM366_ERC366  2018-01-03T00:00:00-02:00      3.2529
11830  2018    4      1  GM366_ERC366  2018-01-04T00:00:00-02:00      3.2312
11831  2018    5      1  GM366_ERC366  2018-01-05T00:00:00-02:00      3.2403
11832  2018    8      1  GM366_ERC366  2018-01-08T00:00:00-02:00      3.2351
11833  2018    9      1  GM366_ERC366  2018-01-09T00:00:00-02:00      3.2391
11834  2018   10      1  GM366_ERC366  2018-01-10T00:00:00-02:00      3.2461
11835  2018   11      1  GM366_ERC366  2018-01-11T00:00:00-02:00      3.2295
11836  2018   12      1  GM366_ERC366  2018-01-12T00:00:00-02:00      3.2192
11837  2018   15      1  GM366_ERC366  2018-01-15T00:00:00-02:00      3.1957
...     ...  ...    ...           ...                        ...         ...
[340 rows x 6 columns]
```

--------------------------------

### Accessing timeseries help documentation

Source: https://github.com/luanborelli/ipeadatapy/blob/master/notebooks/Ipeadatapy Usage Demonstration.ipynb

Use the Python help function to view the signature and parameter descriptions for the timeseries function.

```python
help(idpy.timeseries)
```

--------------------------------

### Import ipeadatapy Library

Source: https://github.com/luanborelli/ipeadatapy/blob/master/notebooks/Ipeadatapy Usage Demonstration.ipynb

Import the ipeadatapy library to begin using its functionalities. This is the initial step for all operations.

```python
import ipeadatapy as idpy
```

--------------------------------

### Accessing Function Help

Source: https://github.com/luanborelli/ipeadatapy/blob/master/docs/source/usage/quickstart/basics.rst

Use the help function to view all available parameters for the timeseries method.

```python
help(ipeadatapy.timeseries)
```

--------------------------------

### Import ipeadatapy

Source: https://github.com/luanborelli/ipeadatapy/blob/master/docs/source/usage/quickstart/extraction.rst

Initial import required to access the package functionality.

```python
import ipeadatapy
```

--------------------------------

### List All Available Data Sources

Source: https://context7.com/luanborelli/ipeadatapy/llms.txt

Retrieve all available data sources in Ipeadata, including their acronyms for filtering metadata queries. Displays the first 20 sources.

```python
import ipeadatapy as ipea

# Get all available data sources
all_sources = ipea.sources()
print(f"Total sources: {len(all_sources)}")
print(all_sources.head(20))
# Output:
# 0       ABCR
# 1       ABPO
# 2       ANDA
# 3       ANFAVEA
# 4       ANP
# 5       BCB
# ...

# Use a source to filter metadata
bcb_meta = ipea.metadata(source="BCB")
print(f"Central Bank (BCB) series: {len(bcb_meta)}")
```

--------------------------------

### Retrieve Data Sources

Source: https://github.com/luanborelli/ipeadatapy/blob/master/docs/source/usage/quickstart/metadata.rst

Lists all data sources available in the Ipeadata database.

```python
ipeadatapy.sources()
```

--------------------------------

### List Data Sources

Source: https://context7.com/luanborelli/ipeadatapy/llms.txt

The `sources` function returns all available data sources in Ipeadata, showing the acronyms that can be used to filter metadata queries.

```APIDOC
## sources - List Data Sources

### Description
Returns all available data sources in Ipeadata, showing the acronyms that can be used to filter metadata queries.

### Method
`ipea.sources()`

### Parameters
None

### Request Example
```python
import ipeadatapy as ipea

all_sources = ipea.sources()
print(f"Total sources: {len(all_sources)}")
print(all_sources.head(20))
```

### Response
#### Success Response (200)
- **sources** (list) - A list of strings, where each string is an acronym for a data source.

#### Response Example
```
0       ABCR
1       ABPO
2       ANDA
3       ANFAVEA
4       ANP
5       BCB
...
```
```

--------------------------------

### Retrieve available themes

Source: https://github.com/luanborelli/ipeadatapy/blob/master/notebooks/Ipeadatapy Usage Demonstration.ipynb

Fetches a list of thematic categories available in the Ipeadata database.

```python
idpy.themes()
```

--------------------------------

### Retrieve and Filter Themes

Source: https://github.com/luanborelli/ipeadatapy/blob/master/docs/source/usage/quickstart/metadata.rst

Lists available themes, with optional filtering by macro, regional, or social categories.

```python
ipeadatapy.themes()
```

```python
ipeadatapy.themes(macro=1)
```

```python
ipeadatapy.themes(macro=1, regional=1)
```

--------------------------------

### Fetch Time Series Data by Day

Source: https://github.com/luanborelli/ipeadatapy/blob/master/notebooks/Ipeadatapy Usage Demonstration.ipynb

Retrieve data for a specific day, month, and year.

```python
idpy.timeseries("GM366_ERC366", year=2019, month=4, day=1)
```

--------------------------------

### Fetch Time Series Data by Month

Source: https://github.com/luanborelli/ipeadatapy/blob/master/notebooks/Ipeadatapy Usage Demonstration.ipynb

Retrieve data for a specific month and year using the timeseries method.

```python
idpy.timeseries("GM366_ERC366", year=2019, month=4)
```

--------------------------------

### Retrieve Available Countries

Source: https://github.com/luanborelli/ipeadatapy/blob/master/docs/source/usage/quickstart/metadata.rst

Lists all countries available in the Ipeadata database.

```python
ipeadatapy.countries()
```

--------------------------------

### Retrieve available countries

Source: https://github.com/luanborelli/ipeadatapy/blob/master/notebooks/Ipeadatapy Usage Demonstration.ipynb

Fetches a list of countries available in the Ipeadata database.

```python
idpy.countries()
```

--------------------------------

### Filter Themes by Macroeconomics

Source: https://github.com/luanborelli/ipeadatapy/blob/master/notebooks/Ipeadatapy Usage Demonstration.ipynb

Use the `macro=1` parameter to retrieve themes related to macroeconomics. This is useful for focusing on economic indicators and policies.

```python
idpy.themes(macro=1)
```

--------------------------------

### List and Search Time Series

Source: https://github.com/luanborelli/ipeadatapy/blob/master/docs/source/usage/quickstart/basics.rst

Retrieve a list of all available time series or filter them using a keyword.

```python
ipeadatapy.list_series()
```

```python
ipeadatapy.list_series('BPM6')
```

--------------------------------

### List All Available Themes

Source: https://context7.com/luanborelli/ipeadatapy/llms.txt

Retrieve all thematic categories used to organize time series in Ipeadata. Supports filtering by ID or name, and theme codes can be used to filter metadata.

```python
import ipeadatapy as ipea

# Get all available themes
all_themes = ipea.themes()
print(f"Total themes: {len(all_themes)}")
print(all_themes.head(20))
# Output:
#    ID                          NAME
# 0   1              Balanço de pagamentos
# 1   2              Câmbio
# 2   3              Comércio exterior
# ...

# Filter by specific theme ID
theme_4 = ipea.themes(theme_id=4)
print(theme_4)

# Filter by theme name
production_theme = ipea.themes(name="Produção")
print(production_theme)

# Use theme code to filter metadata
production_series = ipea.metadata(theme_id=5)
print(f"Production theme series: {len(production_series)}")
```

--------------------------------

### Describe a Time Series

Source: https://context7.com/luanborelli/ipeadatapy/llms.txt

The `describe` function provides a formatted summary of a single time series, displaying all its key metadata attributes in a readable tabular format. This is useful for quickly understanding a series before retrieving its data.

```APIDOC
## describe - Describe a Time Series

### Description
Provides a formatted summary of a single time series, displaying all its key metadata attributes in a readable tabular format.

### Method
`ipea.describe(series_code: str)`

### Parameters
#### Path Parameters
- **series_code** (str) - Required - The code of the time series to describe.

### Request Example
```python
import ipeadatapy as ipea

description = ipea.describe("BM12_PIB12")
print(description)
```

### Response
#### Success Response (200)
- **description** (str) - A formatted string containing the time series metadata.

#### Response Example
```
                             Produto interno bruto (PIB)...
Name                         Produto interno bruto (PIB)...
Code                         BM12_PIB12
Big Theme                    Macroeconômico
Theme code                   4
Source                       Banco Central do Brasil
Source acronym               BCB
Comment                      ...
Last update                  2024-01-15T...
Frequency                    Mensal
Measure                      R$ (milhões)
Unit                         Índice
Status                       A
```
```

--------------------------------

### Retrieve Time Series Data

Source: https://github.com/luanborelli/ipeadatapy/blob/master/notebooks/Ipeadatapy Usage Demonstration.ipynb

Fetches the full dataset for a specified time series code.

```python
idpy.timeseries("GM366_ERC366")
```

--------------------------------

### Perform Direct API Calls with api_call

Source: https://context7.com/luanborelli/ipeadatapy/llms.txt

Provides raw access to Ipeadata API endpoints. Returns data as a pandas DataFrame.

```python
import ipeadatapy as ipea

# Direct API call to metadata endpoint
api_url = "http://www.ipeadata.gov.br/api/odata4/Metadados"
raw_metadata = ipea.api_call(api_url)
print(f"Raw columns: {raw_metadata.columns.tolist()}")
print(raw_metadata.head())

# Direct call to values endpoint for a specific series
series_api = "http://ipeadata.gov.br/api/odata4/ValoresSerie(SERCODIGO='BM12_PIB12')"
raw_values = ipea.api_call(series_api)
print(raw_values.head())

# Direct call to territories endpoint
territories_api = "http://ipeadata.gov.br/api/odata4/Territorios"
raw_territories = ipea.api_call(territories_api)
print(raw_territories.columns.tolist())
```

--------------------------------

### Filter metadata with ipeadatapy

Source: https://github.com/luanborelli/ipeadatapy/blob/master/docs/source/usage/quickstart/advanced_filtering.rst

Use the metadata function with specific keyword arguments to filter results. Refer to help(idpy.metadata) for a complete list of available filtering parameters.

```python
ipeadatapy.metadata(big_theme="Macroeconmico", country="USA", source="Economist", frequency="Trimestral")
```

```python
help(idpy.metadata)
```

--------------------------------

### api_call - Direct API Access

Source: https://context7.com/luanborelli/ipeadatapy/llms.txt

Provides direct access to the Ipeadata API for advanced users, returning raw data as a pandas DataFrame.

```APIDOC
## api_call - Direct API Access

### Description
The `api_call` function provides direct access to the Ipeadata API for advanced users who need raw data or want to query endpoints not covered by other functions. It returns the API response as a pandas DataFrame.

### Method
GET (for the underlying API calls)

### Endpoint
Accepts a full API URL as input.

### Parameters
#### Query Parameters
- **api_url** (string) - Required - The full URL of the Ipeadata API endpoint to call.

### Request Example
```python
import ipeadatapy as ipea

# Direct API call to metadata endpoint
api_url = "http://www.ipeadata.gov.br/api/odata4/Metadados"
raw_metadata = ipea.api_call(api_url)
print(f"Raw columns: {raw_metadata.columns.tolist()}")
print(raw_metadata.head())

# Direct call to values endpoint for a specific series
series_api = "http://ipeadata.gov.br/api/odata4/ValoresSerie(SERCODIGO='BM12_PIB12')"
raw_values = ipea.api_call(series_api)
print(raw_values.head())

# Direct call to territories endpoint
territories_api = "http://ipeadata.gov.br/api/odata4/Territorios"
raw_territories = ipea.api_call(territories_api)
print(raw_territories.columns.tolist())
```

### Response
#### Success Response (200)
A pandas DataFrame containing the raw data returned by the specified API endpoint.

#### Response Example
For metadata endpoint:
```
Raw columns: ['CODMUNICIPIO', 'NOME', 'CODREGIAO', 'NOME_REGIAO', ...]
  CODMUNICIPIO NOME CODREGIAO NOME_REGIAO  CODGRANDE REGIAO NOMEGRANDE REGIAO
0        NaN  NaN       NaN         NaN        NaN               NaN
1        NaN  NaN       NaN         NaN        NaN               NaN
...
```
For values endpoint:
```
  SERCODIGO  VALDATA  VALVALOR
0  BM12_PIB12 2000-01-01  1000.0
1  BM12_PIB12 2001-01-01  1100.0
...
```
```

--------------------------------

### Describe Time Series Metadata

Source: https://github.com/luanborelli/ipeadatapy/blob/master/notebooks/Ipeadatapy Usage Demonstration.ipynb

Retrieve comprehensive metadata for a time series using its unique code.

```python
idpy.describe("GM366_ERC366")
```

--------------------------------

### Track Recent Data Updates with latest_updates

Source: https://context7.com/luanborelli/ipeadatapy/llms.txt

Retrieves time series sorted by their last update date. Useful for monitoring when key economic indicators are refreshed.

```python
import ipeadatapy as ipea

# Get all series sorted by last update
updates = ipea.latest_updates()
print(updates.head(20))
# Output:
#              CODE                                              NAME          LAST UPDATE
# 123    BM12_PIB12              Produto interno bruto (PIB) ...     2024-01-15T10:30:00...
# 456    PRECOS12_IPCA12         IPCA - Índice de Preços ...        2024-01-14T15:20:00...
# ...

# Check for series updated on a specific date
today_updates = updates[updates['LAST UPDATE'].str.contains('2024-01')]
print(f"Series updated in January 2024: {len(today_updates)}")

# Get the 10 most recently updated series
print("Most recent updates:")
for idx, row in updates.head(10).iterrows():
    print(f"  {row['CODE']}: {row['NAME'][:50]}... ({row['LAST UPDATE'][:10]})")
```

--------------------------------

### metadata

Source: https://context7.com/luanborelli/ipeadatapy/llms.txt

Retrieves comprehensive metadata for time series, including source, theme, frequency, and measurement units.

```APIDOC
## metadata

### Description
Returns metadata for all time series or a specific series, allowing filtering by various attributes.

### Parameters
#### Path Parameters
- **code** (string) - Optional - The unique identifier for a specific series.

#### Query Parameters
- **big_theme** (string) - Optional - Filter by broad economic theme.
- **source** (string) - Optional - Filter by data source acronym.
- **frequency** (string) - Optional - Filter by update frequency (e.g., 'Mensal').
- **country** (string) - Optional - Filter by country code.

### Response
#### Success Response (200)
- **DataFrame** (pandas.DataFrame) - A DataFrame containing metadata fields like NAME, SOURCE, FREQUENCY, MEASURE, and LAST UPDATE.
```

--------------------------------

### List Available Themes

Source: https://context7.com/luanborelli/ipeadatapy/llms.txt

The `themes` function returns all thematic categories used to organize time series in Ipeadata. Themes can be filtered by ID or name, and are used to classify data into topical groupings.

```APIDOC
## themes - List Available Themes

### Description
Returns all thematic categories used to organize time series in Ipeadata. Themes can be filtered by ID or name.

### Method
`ipea.themes(theme_id: int = None, name: str = None)`

### Parameters
#### Query Parameters
- **theme_id** (int) - Optional - Filters themes by their ID.
- **name** (str) - Optional - Filters themes by their name.

### Request Example
```python
import ipeadatapy as ipea

# Get all available themes
all_themes = ipea.themes()
print(f"Total themes: {len(all_themes)}")

# Filter by specific theme ID
theme_4 = ipea.themes(theme_id=4)
print(theme_4)

# Filter by theme name
production_theme = ipea.themes(name="Produção")
print(production_theme)
```

### Response
#### Success Response (200)
- **themes** (list) - A list of dictionaries, where each dictionary represents a theme with 'ID' and 'NAME' keys.

#### Response Example
```
   ID                          NAME
0   1              Balanço de pagamentos
1   2              Câmbio
2   3              Comércio exterior
...
```
```

--------------------------------

### Retrieve Time Series Data with Month Filtering

Source: https://github.com/luanborelli/ipeadatapy/blob/master/notebooks/Ipeadatapy Usage Demonstration.ipynb

Fetches time series data for a specific code and year, restricted to a range of months using monthGreaterThan and monthSmallerThan parameters.

```python
idpy.timeseries("GM366_ERC366", year=2018, monthGreaterThan=5, monthSmallerThan=13)
```

--------------------------------

### Retrieve Time Series Data - Python

Source: https://context7.com/luanborelli/ipeadatapy/llms.txt

The `timeseries` function fetches data for a given series code. It supports filtering by year, month, and day using comparison operators.

```python
import ipeadatapy as ipea
import matplotlib.pyplot as plt

# Retrieve full time series data
# BM12_PIB12 = Brazilian GDP monthly
gdp_data = ipea.timeseries("BM12_PIB12")
print(gdp_data.head())
# Output:
#             CODE  VALUE (...)  YEAR  DAY  MONTH     RAW DATE
# DATE
# 1990-01-01  BM12_PIB12    1234.56  1990    1      1  1990-01-01T00:00:00...
# ...

```

```python
# Filter data by specific year
gdp_2022 = ipea.timeseries("BM12_PIB12", year=2022)
print(f"Records in 2022: {len(gdp_2022)}")
```

```python
# Filter data by year range (greater than 2019, smaller than 2024)
gdp_recent = ipea.timeseries("BM12_PIB12", yearGreaterThan=2019, yearSmallerThan=2024)
print(f"Records 2020-2023: {len(gdp_recent)}")
```

```python
# Filter by specific month across all years
january_data = ipea.timeseries("BM12_PIB12", month=1)
print(f"January records: {len(january_data)}")
```

```python
# Combine multiple filters
q1_2022 = ipea.timeseries("BM12_PIB12", year=2022, monthSmallerThan=4)
print(f"Q1 2022 records: {len(q1_2022)}")
```

```python
# Plot the time series
gdp_data.plot(y='VALUE (%)', figsize=(12, 6), title='Brazilian GDP')
plt.show()
```

--------------------------------

### List All Available Territories

Source: https://context7.com/luanborelli/ipeadatapy/llms.txt

Retrieve all geographic territories in Ipeadata, including states and municipalities. Supports filtering by name, administrative level, territory ID, area size, and capital status.

```python
import ipeadatapy as ipea

# Get all territories
all_territories = ipea.territories()
print(f"Total territories: {len(all_territories)}")
print(all_territories.head())
# Output:
#          NAME        ID           LEVEL        AREA  CAPITAL
# 0      Brasil         0           País  8515767.049    False
# 1      Norte          1          Região  3853676.948    False
# ...

# Filter by administrative level
states = ipea.territories(level="Estado")
print(f"States: {len(states)}")
print(states[['NAME', 'ID', 'AREA']].head(10))

# Filter by area size (territories larger than 500,000 km²)
large_territories = ipea.territories(areaGreaterThan=500000)
print(f"Large territories: {len(large_territories)}")

# Get only state capitals
capitals = ipea.territories(capital=True)
print(f"Capital cities: {len(capitals)}")
print(capitals[['NAME', 'LEVEL']].head())

# Combine filters: small municipalities
small_municipalities = ipea.territories(level="Município", areaSmallerThan=100)
print(f"Small municipalities (<100 km²): {len(small_municipalities)}")
```

--------------------------------

### List all Ipeadata time series

Source: https://github.com/luanborelli/ipeadatapy/blob/master/notebooks/Ipeadatapy Usage Demonstration.ipynb

Retrieves a DataFrame containing all available time series codes and their corresponding names.

```python
idpy.list_series()
```

--------------------------------

### describe(series)

Source: https://github.com/luanborelli/ipeadatapy/blob/master/docs/source/usage/functions/describe.rst

Retrieves descriptive information for a specific time series identified by its code.

```APIDOC
## describe(series)

### Description
Describes the specified time series. The function requires the unique time series code to return metadata.

### Parameters
#### Path Parameters
- **series** (str) - Required - Time series code

### Request Example
```python
import ipeadatapy
ipeadatapy.describe('series_code_here')
```
```

--------------------------------

### Plot Timeseries Data

Source: https://github.com/luanborelli/ipeadatapy/blob/master/notebooks/Ipeadatapy Usage Demonstration.ipynb

This endpoint visualizes timeseries data by plotting specified columns.

```APIDOC
## Plot Timeseries Data

### Description
Visualizes the retrieved timeseries data by plotting specified columns against each other. Typically used to plot a time-based column against a value column.

### Method
GET (Implicit through library function)

### Endpoint
Not applicable (Function call within a library)

### Parameters
#### Path Parameters
- **x_column** (string) - Required - The name of the column to be used for the x-axis.
- **y_column** (string) - Required - The name of the column to be used for the y-axis.

### Request Example
```python
idpy.timeseries("GM366_ERC366", year=2019, month=4).plot("DAY", "VALUE (R$)")
```

### Response
#### Success Response (200)
- Returns a matplotlib AxesSubplot object representing the plot.

#### Response Example
```
<matplotlib.axes._subplots.AxesSubplot object at 0x...>
```
```

--------------------------------

### Retrieve Time Series Data

Source: https://github.com/luanborelli/ipeadatapy/blob/master/docs/source/usage/quickstart/basics.rst

Fetch the actual historical data for a specific time series.

```python
ipeadatapy.timeseries('BPAG_AR')
```

--------------------------------

### Fetch Timeseries Data

Source: https://github.com/luanborelli/ipeadatapy/blob/master/notebooks/Ipeadatapy Usage Demonstration.ipynb

This endpoint retrieves time series data for a given code. It supports filtering by year, month, and day, or by year ranges.

```APIDOC
## Fetch Timeseries Data

### Description
Retrieves time series data for a specified code. You can filter the data by providing specific year, month, and day parameters, or by specifying a minimum year using `yearGreaterThan`.

### Method
GET (Implicit through library function)

### Endpoint
Not applicable (Function call within a library)

### Parameters
#### Query Parameters
- **code** (string) - Required - The code for which to retrieve timeseries data.
- **year** (integer) - Optional - Filters data for a specific year.
- **month** (integer) - Optional - Filters data for a specific month (requires `year`).
- **day** (integer) - Optional - Filters data for a specific day (requires `year` and `month`).
- **yearGreaterThan** (integer) - Optional - Filters data for years greater than the specified value.

### Request Example
```python
idpy.timeseries("GM366_ERC366", year=2019, month=4)
```

### Response
#### Success Response (200)
- **YEAR** (integer) - The year of the data point.
- **DAY** (integer) - The day of the data point.
- **MONTH** (integer) - The month of the data point.
- **CODE** (string) - The code associated with the data.
- **DATE** (string) - The date and time of the data point.
- **VALUE (R$)** (float) - The value of the data point in Brazilian Reais.

#### Response Example
```json
{
  "YEAR": 2019,
  "DAY": 1,
  "MONTH": 4,
  "CODE": "GM366_ERC366",
  "DATE": "2019-04-01T00:00:00-03:00",
  "VALUE (R$)": 3.8676
}
```
```

--------------------------------

### Retrieve Time Series Data for a Specific Year

Source: https://github.com/luanborelli/ipeadatapy/blob/master/notebooks/Ipeadatapy Usage Demonstration.ipynb

Use the 'timeseries' function with the 'year' parameter to filter data for a particular year. This is useful for analyzing yearly trends.

```python
idpy.timeseries("GM366_ERC366", year=2019)
```

--------------------------------

### Filter Time Series by Year Range

Source: https://github.com/luanborelli/ipeadatapy/blob/master/notebooks/Ipeadatapy Usage Demonstration.ipynb

Retrieve data filtered by a minimum year threshold.

```python
idpy.timeseries("GM366_ERC366", yearGreaterThan=2013)
```