Pacífico Python Client

Official Python interface for requesting financial values, structured reports, metadata, and hosted applications from the Pacífico API.

The package exposes one primary function—pacifico.request(...)—and handles request serialization, API-key authentication, asynchronous result polling, JSON parsing, and optional file output.

Access required: The package is installable from PyPI, but API usage requires a token issued by Pacifico Research.

Contents

• Installation
• Quick start
• Authentication
• Requesting values
• Requesting reports
• Metadata discovery
• Hosted applications
• Request reference
• Response formats
• Saving results
• How delivery works
• Development
• License

Installation

Pacífico supports Python 3.6 or later according to the package metadata.

python -m pip install pacifico

For an isolated environment:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install pacifico

Quick start

Store the token supplied by Pacifico Research in token.key, then request a ticker:

import pacifico

values = pacifico.request("token.key", ticker="BCP0600323")
print(values)

The default result is a pandas.DataFrame. You may also pass the token value directly, but a token file is safer for local development when it is excluded from version control.

Authentication

The token argument accepts:

• the API token as a string;
• a path ending in .key or .txt; or
• an empty value, in which case the client reads token.key from the current working directory.

# Explicit token file (recommended for local use)
data = pacifico.request("/secure/path/pacifico.key", ticker="CHILE")

# Implicit ./token.key
data = pacifico.request(ticker="CHILE")

Never commit a real token, paste one into a notebook output, or include one in support logs. Tokens determine both identity and the enabled usage plan.

Requesting values

Value requests can target one or more tickers or progressively broader levels of the instrument hierarchy:

Country → Market → Group → Family → Ticker

import pacifico

token = "token.key"

# One ticker
bond = pacifico.request(token, ticker="BCP0600323")

# Multiple tickers
portfolio = pacifico.request(token, ticker=["CHILE", "BCP0600323"])

# Hierarchy filters
family = pacifico.request(token, family="BCP")
group = pacifico.request(token, group="BT")
market = pacifico.request(token, market="RF")

# Select an author/source
central_bank = pacifico.request(token, author="BCCh")

Historical values

Use datetime.date or datetime.datetime values for dateStart and dateEnd:

from datetime import date, timedelta

import pacifico

end = date.today()
start = end - timedelta(days=7)

history = pacifico.request(
    "token.key",
    ticker="CHILE",
    dateStart=start,
    dateEnd=end,
)

Historical ranges must be ticker-specific. Broad family, group, market, or country requests are served as current/latest queries even when a historical range is supplied. A single-date request is permitted.

Field, version, and quality filters

String values are accepted for fieldType; enum values are used for fixing, version type, and quality:

from pacifico import Fixing, Quality, VersionType

import pacifico

prices = pacifico.request(
    "token.key",
    ticker="BCP0600323",
    fieldType="Price",
    fixing=Fixing.EOD,
    versionType=VersionType.Version_Pricing,
    quality=Quality.Quality_Production,
)

Available value fields include Price, Yield, Duration, Convexity, Delta, Gamma, Vega, Volatility, Quote, Clean Price, Clean Quote, and Market Presence. Leaving fieldType empty returns all available fields.

Requesting reports

Report requests are selected automatically when any report hierarchy argument is present:

Document → Chapter → Section → Subsection → Paragraph → Item

import pacifico

token = "token.key"

# Reports associated with an entity
entity = pacifico.request(token, item="97004000-5")

# Instrument characteristics and related reports
instrument = pacifico.request(token, item="BCP0600323")

# A document across available items
identifications = pacifico.request(token, document="Identification")

# Combine hierarchy filters
balance_sheet = pacifico.request(
    token,
    document="Balance Sheet",
    item="96800570-7",
)

Report values are typed variants and may contain booleans, numbers, strings, dates, datetimes, URLs, files, browser content, or lists. Historical report ranges should specify both document and item; otherwise the service may normalize the request to current/latest data.

Metadata discovery

Use metadata before building broad or user-selectable queries.

import pacifico

token = "token.key"

# Entire value universe: authors, markets, groups, families, and tickers
value_metadata = pacifico.request(token)

# Value metadata filtered to a family
bcp_metadata = pacifico.request(token, family="BCP", ticker="metadata")

# Report universe: authors, documents, and items
report_metadata = pacifico.request(token, document="metadata")

# Reports available for one item
item_metadata = pacifico.request(
    token,
    document="metadata",
    item="97004000-5",
)

Passing metadata in an instrument filter selects value metadata. Passing it in document, chapter, section, subsection, paragraph, or item selects report metadata.

Hosted applications

Set app to route a request to a hosted financial application. Application names and accepted arguments depend on the caller's access and the server-side application catalog.

import pacifico

# Discover an application's argument contract
help_data = pacifico.request(
    "token.key",
    app="<APPLICATION_NAME>",
    help=True,
)

# Run it; additional keyword arguments are forwarded to the application
result = pacifico.request(
    "token.key",
    app="<APPLICATION_NAME>",
    help=False,
    ticker="CHILE",
    customArgument="value",
)

When the application contract marks an argument as a file, the client uploads the referenced local file to temporary storage and forwards its URL. Application requests use the same asynchronous delivery and output conversion as value and report requests.

Request reference

pacifico.request(
    token="",
    ticker="", family="", group="", market="", country="",
    document="", item="", chapter="", section="", subsection="", paragraph="",
    app="", help=False,
    dateStart=date.today(), dateEnd=date.today(),
    fixing=Fixing.EOD,
    fieldType="",
    versionType=VersionType.Version_Unspecified,
    author="", version="", quality=Quality.Quality_Unspecified,
    timeOut=300,
    fileName="", format="dataFrame",
    **kwargs,
)

Public enums are importable from the package:

from pacifico import Country, Fixing, Quality, VersionType

Response formats

DataFrame (default)

data = pacifico.request("token.key", ticker="BCP0600323")

Value DataFrames contain:

Scenario, Date Publication, Date Effective, Country, Market, Group,
Family, Ticker, Value, Field, Date Tenor, Other

Report DataFrames contain:

Author, Document, Chapter, Section, Subsection, Paragraph, Item,
Date Publication, Date Effective, Fixing, Value, Value Type,
Date Tenor, Other

Date columns are converted to Python/pandas date-time objects where possible.

Dictionary

data = pacifico.request(
    "token.key",
    ticker="BCP0600323",
    format="dictionary",
)

The result is the decoded nested API response.

JSON

data = pacifico.request(
    "token.key",
    ticker="BCP0600323",
    format="json",
)

The result is the raw JSON string.

Value JSON follows this hierarchy:

Scenario → Publication date → Effective date → Country → Market
         → Group → Family → Ticker → [{value, field, dateTenor?, other?}]

Report JSON follows this hierarchy:

Author → Publication date → Effective date → Document → Chapter
       → Section → Subsection → Paragraph → Item
       → [{variant: {value, type}, dateTenor?, other?}]

Saving results

Pass a base path through fileName. The client chooses the extension from the response format:

# Writes pacifico_data.csv
pacifico.request(
    "token.key",
    ticker="BCP0600323",
    format="dataFrame",
    fileName="pacifico_data",
)

# Writes pacifico_data.txt
pacifico.request(
    "token.key",
    ticker="BCP0600323",
    format="json",
    fileName="pacifico_data",
)

DataFrames are written as CSV without the index. JSON strings and dictionaries are written as JSON text.

How delivery works

1. The client serializes a value, report, or application service request.
2. It sends the request to the API with the token in x-api-key.
3. The API immediately returns a pre-signed result URL and processes the request asynchronously.
4. The client polls that URL until the result is ready.
5. The JSON payload is converted to the requested local format and optionally saved.

If processing exceeds timeOut, the client raises TimeoutError. Increase the timeout for legitimately large report or application requests; avoid unbounded retries.

Tutorials

The repository includes two detailed, executable Spanish-language notebooks:

• TutorialValues.ipynb — values, metadata, historical ranges, formats, saving, and the value hierarchy.
• TutorialReports.ipynb — report discovery, hierarchy filters, typed results, formats, and saving.

The examples in this README intentionally use placeholders or token-file paths. Replace only the local token file contents—never commit the issued credential.

Development

Clone with the shared private submodule and install the package in editable mode:

git clone --recurse-submodules <REPOSITORY_URL>
cd pacifico-client
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .

If the repository was already cloned:

git submodule update --init --recursive

Build distributions with:

python -m pip install build
python -m build

The package uses a src layout:

src/pacifico/
├── core/main/pacifico.py          # Public request workflow
├── core/Service/                  # Request and field models
└── util/                          # Arguments, polling, formats, and output

When changing the request contract, keep the client synchronized with the companion Pacífico API server repository and coordinate compatibility-sensitive migrations between releases.

License

Copyright © Pacifico Research. This package is proprietary. Commercial integration, incorporation into a product, or third-party distribution requires an appropriate license from Pacifico Research. Contact Pacifico Research for the current governing terms.