Python SDK

Official Python client for Listings API with typed resources, cursor pagination, automatic retries, and named errors.

The listingsapi package is the official Python client for Listings API. It wraps the REST layer with typed resource classes, cursor-based pagination, automatic retries on transient errors, and a named exception for every failure mode, including error payloads the platform returns with HTTP 200.

Install

pip install listingsapi

Requires Python 3.9 or later. The only runtime dependency is requests.

Authenticate

import listingsapi # Reads LISTINGSAPI_KEY from the environment automaticallyclient = listingsapi.ListingsAPI() # Or pass the key explicitlyclient = listingsapi.ListingsAPI(api_key="your-api-key")

Get your API key from API Keys → New key in the Listings API developer dashboard.

The client takes three optional keyword arguments:

See Configuration for details.

Quick example

import listingsapi client = listingsapi.ListingsAPI() page = client.locations.list(first=5)for loc in page:  print(loc.name, loc.city) print(f"has_more: {page.has_more}")

Resources

Every resource lives under a property of the client:

Four supporting methods live on the client itself:

client.plan_sites()       # directories included in your planclient.subcategories()    # business categories (IDs for locations.add)client.countries()        # supported countries and states (ISO codes)client.subscriptions()    # active subscriptions for the account

Pagination

Methods that return lists use cursor-based pagination. Every paged method returns a SyncPage: iterable, with .has_more, .next_page(), .auto_paging_iter(), and .total.

# Fetch one pagepage = client.locations.list(first=25)for loc in page:  print(loc.name) # Check if more pages existif page.has_more:  next_page = page.next_page() # Auto-paginate through every resultfor loc in client.locations.list(first=100).auto_paging_iter():  print(loc.name)

Response objects

All methods return APIObject (attribute + dict access) or SyncPage (iterable, paged). APIObject also supports .get() and .to_dict().

loc = client.locations.retrieve(16808) # Attribute accessprint(loc.name)print(loc.city) # Dict-style accessprint(loc["stateIso"]) # Safe access with a defaultprint(loc.get("website", "no website")) # Raw dictdata = loc.to_dict()

Error handling

Every SDK error derives from listingsapi.ListingsAPIError. API failures raise APIError or one of its subclasses: AuthenticationError, PermissionDeniedError, NotFoundError, ValidationError, RateLimitError (with .retry_after), and InternalServerError. Network failures raise APIConnectionError.

APIError carries status_code, code (the first platform error code, e.g. SY10005), errors (every entry normalized to {"code", "message", "context"} dicts), and response_body.

The platform reports some failures inside an HTTP 200 body: top-level errors[] payloads (invalid tokens come back as SY90005) and mutation envelopes with success=false. The SDK raises for those too, so you never inspect success flags yourself.

import listingsapi client = listingsapi.ListingsAPI() try:  client.locations.retrieve(999999)except listingsapi.NotFoundError:  print("No such location")except listingsapi.RateLimitError as e:  print(f"Rate limited, retry in {e.retry_after}s")except listingsapi.APIError as e:  print(e.status_code, e.code)  for err in e.errors:      print(err["code"], err["message"])

See Error handling for the full exception hierarchy.

Next steps

• Installation: virtual environments, version pins
• Quickstart: first calls, create a location, respond to a review
• Configuration: timeouts, retries, base URL
• Use cases: end-to-end recipes
• Locations, Reviews, Listings, Analytics