Formats and schemas¶

format controls only the local representation of the delivered response. It does not ask the server for a different data universe.

Supported format strings¶

Input	Return type
"dataFrame", "DataFrame", "df"	pandas.DataFrame
"dictionary", "dict"	dict or other top-level JSON-decoded type
"json", "JSON"	str

The default is "dataFrame". Other spellings return no valid internal format and eventually fail during conversion. Pass a string, not an internal format enum.

JSON¶

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

The normal result is the response text unchanged. One exception exists: a response shorter than 100 characters that contains lowercase error is replaced with:

{"Error": "There has been an internal error processing the request!"}

Use JSON when exact nesting matters, when integrating a new hosted application, or when diagnosing conversion.

Dictionary¶

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

The client applies json.loads to the response. Nested date strings and report variants are not coerced. The short-error case becomes:

{"Error": "There has been an internal error processing the request!"}

Although value and canonical report responses are dictionaries, a valid application or large-report JSON payload can have another top-level type. Type-check before assuming mapping methods are available.

Value JSON schema¶

Canonical value JSON nests shared attributes outside the observation list:

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

Representative shape:

{
  "<SCENARIO>": {
    "31/07/2026": {
      "31/07/2026 12:30:00": {
        "Chile": {
          "RF": {
            "BT": {
              "BCP": {
                "BCP0600323": [
                  {
                    "value": 1.2345,
                    "field": "Price",
                    "dateTenor": "01/03/2032 00:00:00",
                    "other": "<OPTIONAL CONTEXT>"
                  }
                ]
              }
            }
          }
        }
      }
    }
  }
}

dateTenor and other are optional at the observation level. Empty hierarchy keys can still appear in metadata or special responses.

For a non-EOD value, the publication key has the form DD/MM/YYYY-F_HHMM. Preserve that suffix when consuming raw JSON.

Value DataFrame schema¶

Each leaf observation becomes one row with columns in this exact order:

Column	Conversion
Scenario	JSON key, string
Date Publication	DD/MM/YYYY parsed to a Python datetime at midnight
Date Effective	DD/MM/YYYY HH:MM:SS parsed to datetime
Country	JSON key, string
Market	JSON key, string
Group	JSON key, string
Family	JSON key, string
Ticker	JSON key, string
Value	JSON value without field-specific coercion
Field	field string
Date Tenor	Parsed datetime when present; otherwise empty string
Other	Value when present; otherwise empty string

The same ticker and effective timestamp can have multiple rows because each field is a separate observation. Define uniqueness using every dimension relevant to the consuming model.

Latest-value responses omit rows whose effective timestamp is more than 500 days before the server's current date. This freshness rule applies to the latest value formatter, not to historical value queries or latest report formatting.

Report JSON schema¶

Canonical report JSON follows:

Author
└── Publication date
    └── Effective date
        └── Document
            └── Chapter
                └── Section
                    └── Subsection
                        └── Paragraph
                            └── Item
                                └── [{variant, fixing?, dateTenor?, other?}, ...]

Representative shape:

{
  "<AUTHOR>": {
    "31/07/2026": {
      "31/07/2026 17:00:00": {
        "<DOCUMENT>": {
          "<CHAPTER>": {
            "<SECTION>": {
              "<SUBSECTION>": {
                "<PARAGRAPH>": {
                  "<ITEM>": [
                    {
                      "fixing": "EOD",
                      "variant": {
                        "value": "<VALUE>",
                        "type": "String"
                      },
                      "dateTenor": "31/12/2030 00:00:00",
                      "other": "<OPTIONAL CONTEXT>"
                    }
                  ]
                }
              }
            }
          }
        }
      }
    }
  }
}

fixing, dateTenor, and other are optional in each leaf.

Report DataFrame schema¶

Each report leaf becomes one row with columns in this exact order:

Column	Conversion
Author	JSON key, string
Document	JSON key, string
Chapter	JSON key, string
Section	JSON key, string
Subsection	JSON key, string
Paragraph	JSON key, string
Item	JSON key, string
Date Publication	Parsed from DD/MM/YYYY
Date Effective	Parsed from DD/MM/YYYY HH:MM:SS
Fixing	Leaf fixing when present; otherwise empty string
Value	Coerced according to variant.type
Value Type	Human-readable variant type
Date Tenor	Parsed datetime when present; otherwise empty string
Other	Leaf other when present; otherwise empty string

Mixed Value types normally produce a pandas object column.

Large report representation¶

The converter also supports a compact top-level list used for large report results. Its first element is the author; later elements are flat report objects:

[
  "<AUTHOR>",
  {
    "document": "<DOCUMENT>",
    "chapter": "<CHAPTER>",
    "section": "<SECTION>",
    "subsection": "<SUBSECTION>",
    "paragraph": "<PARAGRAPH>",
    "item": "<ITEM>",
    "datePublication": "2026-07-31T00:00:00",
    "dateEffective": "2026-07-31T17:00:00",
    "fixingPublication": -1,
    "variant": "{\"valueType\": 3, \"value\": \"<VALUE>\"}",
    "dateTenor": null,
    "comment": "<OPTIONAL CONTEXT>"
  }
]

In this representation dates are ISO-format strings, variant is itself a JSON string, and comment maps to Other.

Report value types¶

Canonical variant.type labels supported by the DataFrame converter are:

Label	DataFrame Value
Bool	bool
Integer	int
Double	float
String	str
Date	parsed date/datetime object
DateTime	parsed datetime
Url	str
File	str
Browser	str plus browser-opening attempt
List Bool	list[bool]
List Integer	list[int]
List Double	list[float]
List String	list[str]
List Date	list of parsed dates
List DateTime	list of parsed datetimes
List Url	list[str]
List File	list[str]
List Browser	list[str]

String list input is split on commas before element coercion. Boolean coercion uses Python truthiness in the canonical converter; a non-empty string such as "False" can therefore become True. Preserve raw JSON when exact source typing is important.

Browser conversion side effect¶

For a scalar Browser report value, DataFrame conversion:

1. downloads the URL;
2. writes browser.html in the current working directory;
3. starts or reuses a Selenium browser window;
4. opens the temporary file;
5. deletes the temporary file.

Failures are printed and conversion continues. JSON and dictionary modes do not perform this display behavior.

Error rows¶

DataFrame conversion often represents errors as a one-row DataFrame instead of raising:

• value parsing sets Ticker to Error;
• report parsing sets Document to Error;
• the message appears in Value or Other;
• up to the first 100 response characters can appear in Other.

The short lowercase-error path always produces the value-style schema, even if the original request was a report. Error-row fields can contain internal enum objects rather than the normal strings.

Always validate:

def assert_pacifico_frame(frame):
    if "Ticker" in frame and frame["Ticker"].eq("Error").any():
        raise RuntimeError(frame.loc[frame["Ticker"].eq("Error"), "Other"].iloc[0])
    if "Document" in frame and frame["Document"].eq("Error").any():
        row = frame.loc[frame["Document"].eq("Error")].iloc[0]
        raise RuntimeError(str(row.get("Value", row.get("Other", ""))))

For ambiguous failures, rerun the same narrow request with format="json".