Chile Public Market SDK

Unofficial, typed, synchronous and asynchronous Python SDK for Chile's Mercado Público APIs.

Status: alpha (0.4.0). The upstream services include legacy contracts and may add fields. Models validate known fields while preserving new ones.

Requirements

• Python 3.12 or newer.
• An access ticket requested through ChileCompra.

Installation

pip install chile-public-market-sdk

Secure configuration

The SDK never includes or manages tickets. Pass one explicitly:

from chile_public_market_sdk import SyncChilePublicMarketSDK

sdk = SyncChilePublicMarketSDK(ticket="YOUR_TICKET")

Or define CHILE_PUBLIC_MARKET_TICKET:

export CHILE_PUBLIC_MARKET_TICKET="YOUR_TICKET"

Git ignores .env and env.yaml. Loading them through Docker Compose, Kubernetes, envyaml, python-dotenv, or another secret-management mechanism is the consumer application's responsibility. The SDK itself does not read configuration files.

Synchronous usage

from datetime import date

from chile_public_market_sdk import SyncChilePublicMarketSDK
from chile_public_market_sdk.core.enums import TenderStatus

with SyncChilePublicMarketSDK() as client:
    response = client.get_tenders(
        date=date(2026, 6, 12),
        status=TenderStatus.PUBLISHED,
    )
    for tender in response.items:
        print(tender.external_code, tender.name)

    order = client.get_purchase_orders(code="2097-241-SE14")
    supplier = client.find_supplier("70.017.820-k")
    buyers = client.get_buyers()

Asynchronous usage

import asyncio

from chile_public_market_sdk import AsyncChilePublicMarketSDK
from chile_public_market_sdk.core.enums import AgilePurchaseStatus


async def main() -> None:
    async with AsyncChilePublicMarketSDK() as client:
        page = await client.get_agile_purchases(
            last_change_ttl_ms=300_000,
            statuses=[AgilePurchaseStatus.PUBLISHED],
            page_size=50,
        )
        detail = await client.get_agile_purchase(page.items[0].code)
        print(detail.name)


asyncio.run(main())

Endpoint coverage

V1 date filters accept a date or the original ddmmyyyy format. Agile Purchase accepts ISO-8601 dates, multiple statuses and regions, pagination, and sorting.

Client classes and API versions

The SDK exposes separate synchronous and asynchronous classes:

• SyncChilePublicMarketClient / SyncChilePublicMarketSDK
• AsyncChilePublicMarketClient / AsyncChilePublicMarketSDK

SDK classes construct and own a client through sdk.client. Their context managers return that managed client, while endpoint methods remain on client classes.

ChileCompra endpoint contracts are versioned independently under chile_public_market_sdk.api.v1 and chile_public_market_sdk.api.v2. Future upstream contracts will follow api.v{version}. SDK releases remain 0.x until the public Python API is stable enough for 1.0.0.

Errors

Every public exception inherits from ChilePublicMarketError:

• ConfigurationError: no ticket was supplied.
• RequestValidationError: incompatible or invalid filters.
• AuthenticationError: HTTP 401 or 403.
• NotFoundError: HTTP 404.
• RateLimitError: HTTP 429; exposes retry_after.
• APIError: any other API error.
• RequestTimeoutError: a configured timeout was exceeded.
• NetworkError: a connection or network protocol failed.
• TransportError: another HTTP transport failure.
• ResponseValidationError: invalid JSON or an unexpected contract.

Reliability

The SDK uses HTTPX directly. Pass a native httpx.Timeout for granular limits:

import httpx

from chile_public_market_sdk import ClientConfig, SyncChilePublicMarketSDK

config = ClientConfig(
    ticket="YOUR_TICKET",
    timeout=httpx.Timeout(connect=5, read=30, write=10, pool=5),
)

with SyncChilePublicMarketSDK(config=config) as client:
    tenders = client.get_tenders()

Applications that need retries can inject an HTTPX client configured for their own policy. The SDK does not hide HTTPX behind another transport abstraction.

Development

poetry install --extras "dev docs"
poetry run pytest
poetry run ruff check .
poetry run mypy
poetry run pyright
poetry build

Read CONTRIBUTING.md and SECURITY.md before submitting changes or reporting vulnerabilities.