listingsAPIlistingsAPI
Get API keySign in

Configuration

Configure the listingsAPI Python client: API key, base URL, timeout, retries, and logging.

Constructor signature

listingsapi.ListingsAPI(
    api_key: str | None = None,
    *,
    base_url: str | None = None,
    timeout: float = 240.0,
    max_retries: int = 2,
)

All arguments are optional. If api_key is omitted the client reads LISTINGSAPI_KEY from the environment and raises AuthenticationError at construction time if neither is set.

Options

OptionTypeDefaultDescription
api_keystr | NoneNoneAPI key. Falls back to the LISTINGSAPI_KEY environment variable.
base_urlstr | Nonehttps://listingsapi.comAPI origin. A trailing slash is stripped automatically.
timeoutfloat240.0Per-request timeout in seconds (applies to each HTTP request individually).
max_retriesint2Automatic retries on 429 and 5xx responses. Set to 0 to disable.

API key

bash
export LISTINGSAPI_KEY="your-api-key"
Python
import listingsapi
 
# From environment (recommended)
client = listingsapi.ListingsAPI()
 
# Explicit key
client = listingsapi.ListingsAPI(api_key="your-api-key")

Timeout

Default is 240.0 seconds. For short-lived scripts or interactive use you may want a tighter value:

Python
client = listingsapi.ListingsAPI(timeout=30.0)

The timeout applies to each individual HTTP request. Bulk pagination calls (auto_paging_iter) respect the per-request timeout independently.

Retries

The SDK mounts a urllib3 Retry adapter on its requests session that automatically retries 429, 500, 502, 503, and 504 responses for GET and POST methods. The default is 2 retries with a 0.5-second exponential backoff factor. Retry-After headers are honoured, so a 429 that names a wait time is retried after exactly that long.

Python
# More aggressive retry for long-running batch jobs
client = listingsapi.ListingsAPI(max_retries=5)
 
# Disable retries entirely (e.g. when you want fast failures)
client = listingsapi.ListingsAPI(max_retries=0)

A 429 that survives every retry surfaces as RateLimitError; see Error handling for a manual backoff recipe.

Base URL override

Useful for staging environments or internal proxies:

Python
client = listingsapi.ListingsAPI(base_url="https://staging.example.com")

The trailing slash is stripped automatically. All requests are made under the /api/v4/ path on this origin.

Logging

The SDK logs through the standard logging module under the listingsapi logger. At DEBUG level it records the method and URL of every request (and query parameters for GET); request bodies and your API key are never logged.

Python
import logging
logging.basicConfig()
logging.getLogger("listingsapi").setLevel(logging.DEBUG)
 
import listingsapi
client = listingsapi.ListingsAPI()
client.locations.list(first=1)

Next steps