Listings APIListings API
Get API keySign in

Configuration

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

Constructor signature

Python
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 keyclient = 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, but only for the safe methods: GET, HEAD, and OPTIONS. Writes (POST, DELETE) are sent exactly once and raise the failure immediately. 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.

The v4 API has no Idempotency-Key support and does not detect repeated writes, so a write that times out or returns a 5xx may already have committed. Retrying it blind would create a second location, post, or review reply. Read the record back by a key you control before repeating a write.

Python
# More aggressive retry for long-running batch jobsclient = 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 is raised 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 logginglogging.basicConfig()logging.getLogger("listingsapi").setLevel(logging.DEBUG) import listingsapiclient = listingsapi.ListingsAPI()client.locations.list(first=1)

Next steps