ada-diamonds

Official Python client for the Ada Diamonds API: live lab grown diamond inventory, engagement ring settings, fine jewelry, and diamond buying guides.

Pure Python, no dependencies beyond the standard library. Python 3.9 or newer.

Install

pip install ada-diamonds

Publishing to PyPI is pending. Until the release lands, install from the repository:

pip install "git+https://github.com/adadiamonds/ada-diamonds-nextjs.git#subdirectory=packages/ada-python"

Reading the catalog needs no account and no API key.

Examples

Search live diamond inventory

from ada_diamonds import Client

client = Client()  # anonymous, 120 requests per minute
page = client.diamonds(shape="Oval", min_carat=1, max_price=4000, sort="price_asc")
for stone in page["data"]:
    print(stone["carat"], stone["shape"], stone["color"], stone["clarity"], stone["price"])
print(page["pagination"])      # {'total': ..., 'limit': 25, 'offset': 0, 'has_more': ...}
print(client.last_rate_limit)  # RateLimit({'limit': 120, 'remaining': 119, 'reset': 58, ...})

Quote a complete engagement ring

An engagement ring is a setting plus a loose diamond, priced separately. price_from on a setting excludes the center stone. All prices are US dollars.

setting = client.engagement_rings(shape="Oval", type="Solitaire", limit=1)["data"][0]
stone = client.diamonds(shape="Oval", min_carat=1.5, max_carat=1.6, sort="price_asc", limit=1)["data"][0]
print(setting["name"], "+", stone["carat"], "ct =", setting["price_from"] + stone["price"])

Get a key, then write

from ada_diamonds import AdaApiError, Client

issued = Client().create_key("my-agent", env="sandbox")   # no account needed
client = Client(api_key=issued["api_key"])                  # 600 requests per minute

try:
    result = client.request_consultation(
        {"email": "test@example.com", "topic": "engagement_ring"},
        idempotency_key="consult-0001",
    )
    print(result)  # sandbox keys return {"sandbox": true, ...} and contact nobody
except AdaApiError as exc:
    print(exc.status, exc.error, exc.error_description, exc.documentation_url)

Methods

Errors raise AdaApiError with status, error, error_description, documentation_url, and retry_after_seconds (on 429). After every call client.last_rate_limit holds the RateLimit-* headers and client.last_headers the full header map.

Pass base_url= to point at another host, for example a preview deployment.

Also available

• REST API reference: https://www.adadiamonds.com/developers/api
• OpenAPI 3.1: https://www.adadiamonds.com/openapi.json
• MCP server (Streamable HTTP): https://www.adadiamonds.com/mcp, docs at https://www.adadiamonds.com/developers/mcp
• CLI: npx @ada-diamonds/cli, docs at https://www.adadiamonds.com/developers/cli
• Authentication: https://www.adadiamonds.com/developers/authentication

Support

Developer questions: it@adadiamonds.com. Automated bulk scraping of the site is not permitted; this API is the supported way to read the catalog.

License

MIT