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
Package page: https://pypi.org/project/ada-diamonds/. 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
| Method | Endpoint |
|---|---|
diamonds(**filters) |
GET /api/v1/diamonds |
diamond(id) |
GET /api/v1/diamonds/{id} |
engagement_rings(**filters) |
GET /api/v1/engagement-rings |
engagement_ring(slug) |
GET /api/v1/engagement-rings/{slug} |
jewelry(**filters) |
GET /api/v1/jewelry |
jewelry_item(slug) |
GET /api/v1/jewelry/{slug} |
knowledge_base(q=None) |
GET /api/v1/knowledge-base |
article(slug) |
GET /api/v1/knowledge-base/{slug} |
showrooms() |
GET /api/v1/showrooms |
request_consultation(payload, idempotency_key=None) |
POST /api/v1/consultations |
create_key(name, env="sandbox") |
POST /api/v1/keys |
batch(requests) |
POST /api/v1/batch |
ask(query) |
GET /ask (NLWeb) |
request(method, path, params=None, body=None, headers=None) |
any endpoint |
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
Metadata
Release files for ada-diamonds 1.0.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| ada_diamonds-1.0.1.tar.gz | 10.2 kB | Without provenance | Details for ada_diamonds-1.0.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| ada_diamonds-1.0.1-py3-none-any.whl | Python 3 | none | any | Details for ada_diamonds-1.0.1-py3-none-any.whl |
Total release size: 18.1 kB
Release files / ada_diamonds-1.0.1.tar.gz
| Download URL | ada_diamonds-1.0.1.tar.gz |
|---|---|
| Size | 10.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e2c257260392ccc66d4fbc0d46bf8fbbe5bf2cbe518cf0f739ef718e0fd30f0f
|
|
BLAKE2b-256 checksum How to use checksums |
f30420857479d35a3a41567360ce01b772e8d9eb2877f7de737a2519772a6792
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.0
|
Release files / ada_diamonds-1.0.1-py3-none-any.whl
| Download URL | ada_diamonds-1.0.1-py3-none-any.whl |
|---|---|
| Size | 7.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
55d597d76bed02cb82201ec5b83de20dc6d7be7f8ea0bae7776d8a6de851dfb8
|
|
BLAKE2b-256 checksum How to use checksums |
e86e8a51838e6eea5c7b364231d22dc323304cd92f71e70056ad468686ab376e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.0
|
Security for ada-diamonds 1.0.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.