listingsAPIlistingsAPI
Get API keySign in

Python SDK

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

The listingsapi package is the official Python client for listingsAPI. 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

bash
pip install listingsapi

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

Authenticate

Python
import listingsapi
 
# Reads LISTINGSAPI_KEY from the environment automatically
client = listingsapi.ListingsAPI()
 
# Or pass the key explicitly
client = listingsapi.ListingsAPI(api_key="your-api-key")

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

The client takes three optional keyword arguments:

OptionDefaultDescription
base_urlhttps://listingsapi.comAPI host to send requests to
timeout240.0Per-request timeout in seconds
max_retries2Automatic retries on 429 and 5xx responses, honoring Retry-After

See Configuration for details.

Quick example

list_locations.py
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:

PropertyWhat it manages
client.locationsBusiness locations: list, search, one-call create, update, archive
client.reviewsReviews and responses, plus analytics under client.reviews.analytics
client.postsAnnouncement, event, and offer posts to Google and Facebook
client.listingsPremium and voice listings, duplicates, connect and disconnect
client.analyticsGoogle, Bing, and Facebook profile insights
client.photosLocation photos: upload, remove, star
client.connected_accountsOAuth connections to Google and Facebook
client.workflowsPre-built automations: review auto-reply, reputation report, listings health audit

Four supporting methods live on the client itself:

Python
client.plan_sites()       # directories included in your plan
client.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.

Python
# Fetch one page
page = client.locations.list(first=25)
for loc in page:
  print(loc.name)
 
# Check if more pages exist
if page.has_more:
  next_page = page.next_page()
 
# Auto-paginate through every result
for 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().

Python
loc = client.locations.retrieve(16808)
 
# Attribute access
print(loc.name)
print(loc.city)
 
# Dict-style access
print(loc["stateIso"])
 
# Safe access with a default
print(loc.get("website", "no website"))
 
# Raw dict
data = 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.

Python
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