Python API Guide

Complete guide to using numistalib as a Python library.

Overview

numistalib provides a clean, type-safe Python API for accessing Numista data programmatically. All responses are validated Pydantic models with full type hints.

Basic Usage

Client Setup

Every interaction starts with the client:

from numistalib.client import NumistaApiClient
from numistalib.config import Settings

settings = Settings()  # Loads from .env

with NumistaApiClient(settings) as client:
    # Use services with this client
    pass

The client supports both synchronous and asynchronous operations.

§ 1 Types Service

Search and retrieve coin/banknote/exonumia types.

Import

from numistalib.services.types.service import TypeService

Create Service

service = TypeService(client)

Search Types

results = service.search_types(
    query="dollar",
    page=1,
    count=10,
    lang="en"
)

for coin_type in results:
    print(f"{coin_type.numista_id}: {coin_type.title}")
    print(f"  Issuer: {coin_type.issuer}")
    print(f"  Years: {coin_type.min_year}-{coin_type.max_year}")

Parameters:

query (str, optional): Search keywords
issuer (str, optional): Issuer code
category (str, optional): “coin”, “banknote”, or “exonumia”
year (str, optional): Year or range (e.g., “2020” or “2000-2010”)
catalogue (int, optional): Catalogue ID
number (str, optional): Catalogue number
ruler (int, optional): Ruler ID
material (int, optional): Material ID
date (str, optional): Date or range
size (str, optional): Size in mm or range
weight (str, optional): Weight in grams or range
page (int): Page number (default: 1)
count (int): Results per page (default: 50, max: 50)
lang (str): Language code (default: “en”)

Returns: list[TypeBasic]

Get Type Details

full_type = service.get_type(95420, lang="en")

print(f"Title: {full_type.title}")
print(f"Weight: {full_type.weight}g")
print(f"Diameter: {full_type.size}mm")
print(f"Composition: {full_type.composition}")
print(f"Obverse: {full_type.obverse.description}")
print(f"Reverse: {full_type.reverse.description}")

Parameters:

type_id (int): Numista type ID
lang (str): Language code (default: “en”)

Returns: TypeFull

Async Search (Paginated)

For large datasets, use the async paginated search:

import asyncio
from numistalib.client import NumistaApiClient
from numistalib.services.types.service import TypeService

async def search_all_dollars():
    settings = Settings()
    
    async with NumistaApiClient(settings) as client:
        service = TypeService(client)
        
        all_results = []
        async for coin_type in service.paginated_search(query="dollar"):
            all_results.append(coin_type)
            print(f"Found: {coin_type.title}")
        
        print(f"Total: {len(all_results)}")

asyncio.run(search_all_dollars())

§ 2 Catalogues Service

Access reference catalogue information.

Import & Create

from numistalib.services.catalogues.service import CataloguesService

service = CataloguesService(client)

Get All Catalogues

catalogues = service.get_catalogues()

for cat in catalogues:
    print(f"{cat.id}: {cat.name}")
    print(f"  Author: {cat.author}")
    print(f"  Type: {cat.type}")

Returns: list[Catalogue]

§ 3 Issuers Service

Access issuer (country/entity) information.

Import & Create

from numistalib.services.issuer.service import IssuerService

service = IssuerService(client)

Get All Issuers

issuers = service.get_issuers(lang="en")

for issuer in issuers:
    print(f"{issuer.code}: {issuer.name}")
    if issuer.wikidata_id:
        print(f"  Wikidata: {issuer.wikidata_id}")

Parameters:

lang (str): Language code (default: “en”)

Returns: list[Issuer]

§ 4 Issues Service

Get issue information for types.

Import & Create

from numistalib.services.issues.service import IssuesService

service = IssuesService(client)

Get Type Issues

issues = service.get_issues(type_id=95420, lang="en")

for issue in issues:
    print(f"Issue {issue.id}:")
    print(f"  Years: {issue.min_year}-{issue.max_year}")
    print(f"  Mintage: {issue.mintage}")
    if issue.mint:
        print(f"  Mint: {issue.mint.name}")

Parameters:

type_id (int): Type ID
lang (str): Language code (default: “en”)

Returns: list[Issue]

§ 5 Mints Service

Access mint information.

Import & Create

from numistalib.services.mints.service import MintsService

service = MintsService(client)

List All Mints

mints = service.get_mints(lang="en")

for mint in mints:
    print(f"{mint.id}: {mint.name}")
    if mint.location:
        print(f"  Location: {mint.location}")

Parameters:

lang (str): Language code (default: “en”)

Returns: list[Mint]

Get Mint Details

mint = service.get_mint(mint_id=42, lang="en")

print(f"Name: {mint.name}")
print(f"Location: {mint.location}")
print(f"Period: {mint.start_year}-{mint.end_year}")

Parameters:

mint_id (int): Mint ID
lang (str): Language code (default: “en”)

Returns: Mint

§ 6 Collections Service

Manage user collections (requires OAuth).

Import & Create

from numistalib.services.collections.service import CollectionsService

service = CollectionsService(client)

List User Collections

collections = service.get_collections(user_id=12345)

for collection in collections:
    print(f"{collection.id}: {collection.name}")
    print(f"  Items: {collection.count}")

Parameters:

user_id (int): User ID

Returns: list[Collection]

Get Collection Items

items = service.get_collected_items(
    user_id=12345,
    category="coin",
    collection_id=67890
)

for item in items:
    print(f"Type {item.type}:")
    print(f"  Quantity: {item.quantity}")
    print(f"  Grade: {item.grade}")

Parameters:

user_id (int): User ID
category (str, optional): Filter by category
type_id (int, optional): Filter by type
collection_id (int, optional): Filter by collection

Returns: list[CollectionItem]

§ 7 Image Search Service

Search using coin images.

Import & Create

from numistalib.services.image_search.service import ImageSearchService

service = ImageSearchService(client)

Search by Image

from pathlib import Path

image_path = Path("/path/to/coin.jpg")

results = service.search_by_image(
    image_path=image_path,
    category="coin",
    max_results=20,
    experimental=False,
    lang="en"
)

for result in results:
    print(f"Type {result.type_id}: {result.title}")
    print(f"  Confidence: {result.score}")

Parameters:

image_path (Path): Path to image file
category (str, optional): “coin”, “banknote”, or “exonumia”
max_results (int): Maximum results (default: 100, max: 100)
experimental (bool): Enable experimental features (default: False)
lang (str): Language code (default: “en”)

Returns: list[ImageSearchResult]

§ 8 Literature Service

Get publication information.

Import & Create

from numistalib.services.literature.service import LiteratureService

service = LiteratureService(client)

Get Publication

pub = service.get_publication("L123456")

print(f"Title: {pub.title}")
print(f"Author: {pub.author}")
print(f"Year: {pub.year}")
print(f"Type: {pub.type}")

Parameters:

publication_id (str): Publication ID (e.g., “L123456”)

Returns: Publication

§ 9 Prices Service

Get price estimates for issues.

Import & Create

from numistalib.services.prices.service import PricesService

service = PricesService(client)

Get Price Estimates

prices = service.get_prices(
    type_id=95420,
    issue_id=1,
    currency="USD",
    lang="en"
)

for grade, price in prices.items():
    print(f"{grade}: ${price}")

Parameters:

type_id (int): Type ID
issue_id (int): Issue ID
currency (str): ISO 4217 currency code (default: “EUR”)
lang (str): Language code (default: “en”)

Returns: dict[str, float]

§ 10 Users Service

Get user profile information.

Import & Create

from numistalib.services.users.service import UsersService

service = UsersService(client)

Get User Profile

user = service.get_user(user_id=12345, lang="en")

print(f"Username: {user.username}")
print(f"Member since: {user.member_since}")
print(f"Collection: {user.collection_count} items")

Parameters:

user_id (int): User ID
lang (str): Language code (default: “en”)

Returns: User

§ 11 Async Usage

All services support async operations with _async methods:

import asyncio
from numistalib.client import NumistaApiClient
from numistalib.services.types.service import TypeService

async def main():
    settings = Settings()
    
    async with NumistaApiClient(settings) as client:
        service = TypeService(client)
        
        # Async get
        coin_type = await service.get_type_async(95420)
        print(f"Title: {coin_type.title}")
        
        # Async search with pagination
        async for result in service.paginated_search(query="dollar"):
            print(f"Found: {result.title}")

asyncio.run(main())

§ 12 Working with Models

All responses are Pydantic models with full validation.

Accessing Fields

coin_type = service.get_type(95420)

# Direct access
print(coin_type.title)
print(coin_type.weight)

# Optional fields (may be None)
if coin_type.obverse:
    print(coin_type.obverse.description)

# Nested models
if coin_type.mints:
    for mint in coin_type.mints:
        print(mint.name)

Model Serialization

# To dict
data = coin_type.model_dump()

# To JSON
json_str = coin_type.model_dump_json()

# From dict
from numistalib.models.types import TypeFull
coin_type = TypeFull(**data)

§ 13 Cache Awareness

Check if a response was cached:

from numistalib.client import NumistaResponse

response = service.get_type(95420)

# Access via service's last response (if exposed)
# Or use client directly:
raw_response = client.get("/types/95420")
if isinstance(raw_response, NumistaResponse):
    if raw_response.cached:
        print("💾 Served from cache")
    else:
        print("🌐 Fresh from API")

§ 14 Error Handling

from numistalib.models.errors import NumistaError

try:
    coin_type = service.get_type(99999999)
except NumistaError as e:
    print(f"Error: {e}")
    print(f"Status code: {e.status_code}")

Complete Example

from numistalib.client import NumistaApiClient
from numistalib.config import Settings
from numistalib.services.types.service import TypeService
from numistalib.services.issues.service import IssuesService
from numistalib.services.prices.service import PricesService

settings = Settings()

with NumistaApiClient(settings) as client:
    # Search for types
    types_service = TypeService(client)
    results = types_service.search_types(
        query="commemorative",
        issuer="france",
        year="2010-2020",
        count=5
    )
    
    # Process each type
    for coin_type in results:
        print(f"\n{coin_type.title}")
        print(f"ID: {coin_type.numista_id}")
        
        # Get full details
        full = types_service.get_type(coin_type.numista_id)
        print(f"Weight: {full.weight}g")
        print(f"Composition: {full.composition}")
        
        # Get issues
        issues_service = IssuesService(client)
        issues = issues_service.get_issues(coin_type.numista_id)
        print(f"Issues: {len(issues)}")
        
        # Get prices for first issue
        if issues:
            prices_service = PricesService(client)
            prices = prices_service.get_prices(
                coin_type.numista_id,
                issues[0].id,
                currency="EUR"
            )
            print(f"Prices: {prices}")

Next Steps

Advanced Usage - Complex scenarios
Configuration - Customize behavior
API Reference - Full API documentation