Metadata discovery¶

Metadata requests expose the catalog available to the caller. Use them before constructing selectors, user interfaces, scheduled jobs, or validation lists.

Metadata is data—not a separate client method. The string metadata triggers special server behavior inside a value or report request.

Discover values¶

A request with only a token is value metadata:

import pacifico

catalog = pacifico.request("token.key")

The server returns synthetic value rows using the normal value schema:

• Scenario identifies the author/source;
• Country, Market, Group, Family, and Ticker identify the catalog entry;
• Field is Metadata;
• Value is blank;
• date fields represent metadata generation rather than a market observation.

Build a usable universe from those hierarchy columns:

universe = (
    catalog[
        ["Scenario", "Country", "Market", "Group", "Family", "Ticker"]
    ]
    .drop_duplicates()
    .sort_values(["Country", "Market", "Group", "Family", "Ticker"])
)

Filter value metadata¶

Place metadata in ticker, family, group, or market and use the other selectors as filters:

bcp = pacifico.request(
    "token.key",
    family="BCP",
    ticker="metadata",
)

fixed_income = pacifico.request(
    "token.key",
    market="RF",
    ticker="metadata",
)

The metadata marker itself is not used as a literal hierarchy predicate.

An otherwise empty value request with a non-empty author is not metadata; it becomes a latest-value query. To make discovery intent explicit in reusable code, prefer ticker="metadata".

Discover reports¶

Place metadata in any report selector to select report metadata:

report_catalog = pacifico.request(
    "token.key",
    document="metadata",
)

The report metadata table describes only the available Document, Item, and Author combinations. It is returned through the normal report DataFrame schema, with a typed synthetic metadata value. It is not a complete chapter/section/subsection/paragraph catalog.

Filter the catalog for one item:

item_catalog = pacifico.request(
    "token.key",
    document="metadata",
    item="97004000-5",
)

Although metadata in chapter or lower selectors triggers metadata mode, do not rely on those levels as complete metadata filters: they are not columns in the underlying report metadata catalog.

Authors and current limitations¶

Metadata exposes the author attached to each catalog entry, but author filtering is not uniformly enforced by current request paths. Fetch the appropriate metadata catalog and filter the returned Scenario or Author column client-side:

bcch_values = catalog[
    catalog["Scenario"].str.casefold() == "bcch".casefold()
]

This is safer than assuming author=... restricted the server response. See the limitations on values and reports.

Freshness¶

Metadata refresh is asynchronous and eventually consistent. A newly added ticker or report can become queryable before it appears in the metadata table, or vice versa during an update window.

For resilient integrations:

1. refresh cached metadata on a schedule appropriate to the application;
2. tolerate an entry appearing or disappearing between discovery and retrieval;
3. keep the most recent successful catalog if a refresh fails;
4. avoid treating metadata dates as observation dates;
5. confirm critical identifiers with a narrow request.

Application discovery¶

Hosted applications are dynamic and entitlement-specific. The client has no dedicated, stable application-catalog method. Obtain a permitted application name from Pacifico Research, then query its contract with help=True as described in Hosted applications.