Choose how to integrate

Compare REST, the Python and Node SDKs, the MCP server, and webhooks, then pick the surface that fits your stack and your workload.

Every surface talks to the same API at https://listingsapi.com/api/v4 with the same key, so this is not a one-way choice. Most teams start with one SDK, add webhooks once they are past the first sync, and give their AI tooling the MCP server on the side.

1. Pick a surface

REST directly. Any language, the full surface, no dependency to manage. You handle the response envelope, both pagination styles, and error checking yourself. Choose it when you already have an HTTP client you trust or when you need an endpoint the SDKs do not wrap yet.

Python SDK. pip install listingsapi. Typed resource classes under client.locations, client.reviews, and so on, cursor pages that walk themselves with auto_paging_iter(), retries on 429 and 5xx, and client-side validation on locations.add() so a bad create never leaves your machine. Read Python SDK.

Node SDK. npm install listingsapi-js. TypeScript with bundled types, zero runtime dependencies, Node 18 or later. Methods live flat on the client (client.fetchAllLocations()), fetchAll: true flattens a paginated list, and numeric ids are base64-encoded for you. Read Node SDK.

MCP server. A hosted Streamable HTTP server at https://listingsapi.com/mcp for AI assistants such as Claude and Cursor. There is nothing to install: the assistant can search the docs, browse the REST endpoints, and act on your account with the same tools you would call. Connect with your API key or through OAuth. The dashboard page at /dashboard/mcp shows the exact config to paste into each client and lists every tool with the key level it needs. Step by step for Claude, ChatGPT, Cursor and Gemini: Connect an AI agent with MCP.

Webhooks. Not a replacement for the above but a companion. The API pushes an HTTP POST to one URL on your account when a location, listing, review, or post changes, so you stop polling for changes. Read Webhooks overview.

2. Understand the auth model

Every surface authenticates with an API key. The header is the literal word API, a space, then the key. Keys carry an access level: a Read key covers every lookup and report, and a Write key is needed to create or update anything. A Read key on a write endpoint returns HTTP 400 with SY90016. Keys are per account, so every key shares one rate-limit budget.

OAuth exists for the MCP server only. An MCP client can sign in through the browser instead of pasting a key; REST and the SDKs always use the header. Details are in Authentication.

3. Know the two pagination styles

REST list endpoints paginate in one of two ways, and the SDKs hide the difference. Cursor connections take first and after, and return edges[].node with pageInfo.endCursor. Offset pages take page and perPage, and return records[] with pageInfo.totalRecords.

Here is the same list-locations call on the three code surfaces. Only the cURL version has to read the envelope by hand.

curl "https://listingsapi.com/api/v4/locations?first=5" \-H "Authorization: API $LISTINGSAPI_KEY" # Read data.allLocations.edges[].node, then pass# data.allLocations.pageInfo.endCursor back as ?after= for the next page.

Whatever the surface, a failure comes back as an errors[] array whose message starts with an SY code, and mutations can answer 200 with success: false. Rate limits answer 429 with Retry-After; the Launch plan allows 10 requests a minute. See Error codes and Rate limits.

4. Decide between webhooks and polling

Poll when you need a snapshot on your own schedule, such as a nightly sync of every location, or when an event has no webhook. Use webhooks when latency matters: a new review, a listing going live, a post rejected by Google.

Webhooks are one URL per account, set in the dashboard at /dashboard/webhooks. Every delivery carries an X-ListingsAPI-Signature: sha256=<base64 HMAC> header, you have 5 seconds to answer 2xx, and there are no retries. That last point matters: treat the event as a trigger to read the record back, and keep a timed reconciliation poll as a safety net. React to events with webhooks walks through a receiver.

5. Compare at a glance

Next steps

• Add a location: your first write call, on whichever surface you picked.
• React to events with webhooks: stand up a signed receiver.
• Python SDK and Node SDK: install, configure, and read the method tables.
• Authentication, Rate limits, and Error codes: the three references every surface shares.