Choose how to integrate

Compare the REST API, Python and Node SDKs, MCP server, and webhooks based on your application's architecture and integration requirements.

All integration methods use the same API key and base URL: https://listingsapi.com/api/v4. You can use the REST API or an SDK for API requests, webhooks for event-driven updates, and the MCP server to integrate with the help of an AI agent.

1. Pick how you will call the API

REST API. Use the REST API to access all endpoints directly over HTTP. Your application must parse the response, handle both pagination methods, and inspect the errors[] array for API errors.

Python SDK. Install the Python SDK with pip install listingsapi. The SDK provides resource classes through interfaces such as client.locations and client.reviews. It handles cursor pagination with auto_paging_iter(), retries requests that return 429 or 5xx responses, and validates location payloads in locations.add() before sending the API request. Read Python SDK.

Node SDK. Install the Node SDK with npm install listingsapi-js. It requires Node.js 18 or later, includes TypeScript type definitions, and has no runtime dependencies. SDK methods are exposed directly on the client instance, for example client.fetchAllLocations(). Set fetchAll: true to retrieve all paginated results in a single response. Numeric IDs are automatically Base64-encoded before API requests are sent. Read Node SDK.

MCP server. Connect AI clients such as Claude, ChatGPT, Cursor, and Gemini to the ListingsAPI MCP server at https://listingsapi.com/mcp using Streamable HTTP. No local MCP server installation is required. The server exposes tools for searching ListingsAPI documentation, discovering REST endpoints, and executing supported API operations. Authentication uses an API key or OAuth. Open /dashboard/mcp to view client configuration, available MCP tools, and the API key permission level required for each tool. Connect an AI agent with MCP.

Webhooks. Use webhooks with the REST API, SDKs, or MCP server to receive event-driven updates. When a location, listing, review, or post changes, ListingsAPI sends an HTTP POST request to the webhook URL configured for your account. This allows your application to process changes without polling the API for updates. Read Webhooks overview.

2. Understand the authentication model

The REST API and SDKs authenticate requests using an API key. Pass the key in the HTTP Authorization request header using the API authentication scheme:

Authorization: API <YOUR_API_KEY>

API keys have either Read or Write access. A Read key can access read operations, including lookups and reports. A Write key is required for operations that create or update resources. Sending a Read key to a write endpoint returns HTTP 400 with error code SY90016.

API keys are scoped to an account. Requests made with keys from the same account consume the same account-level rate-limit quota.

The MCP server also supports OAuth authentication. MCP clients can authenticate through the browser using OAuth instead of providing an API key. REST API and SDK requests authenticate using the Authorization header. See the Authentication documentation for configuration details.

3. Understand the pagination models

REST list endpoints use either cursor-based or offset-based pagination. The SDKs abstract these pagination models.

Cursor-based endpoints accept first and after. Results are returned through edges[].node, and pageInfo.endCursor provides the cursor for the next request.

Offset-based endpoints accept page and perPage. Results are returned in records[], and pageInfo.totalRecords reports the total number of available records.

The following examples perform the same list-locations operation using three integration methods. The cURL implementation requires the application to parse the API response structure directly.

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.

For all integration methods, API errors are returned in the errors[] array, with each error message prefixed by an SY error code. Write requests can return HTTP 200 with success: false, so the response body must be checked before treating the operation as successful.

When the account exceeds its rate limit, the API returns HTTP 429 with a Retry-After header. The Launch plan supports up to 10 requests per minute. See the Error codes and Rate limits documentation for details.

4. Choose between webhooks and polling

Use polling when your application needs resource state on a defined schedule, such as a nightly synchronization of all locations, or when the required event does not have webhook support. Use webhooks when your application needs to process changes as they occur, such as receiving a new review, a listing status change, or a rejected Google post.

Configure one webhook URL per account at /dashboard/webhooks. Each webhook request includes an X-ListingsAPI-Signature header in the following format:

X-ListingsAPI-Signature: sha256=<base64 HMAC>

The webhook endpoint must return a 2xx response within 5 seconds. Failed deliveries are not retried.

Use the webhook event as a trigger to retrieve the current resource state from the API. Since webhook deliveries are not retried, run a scheduled reconciliation process to detect updates that may have been missed. See React to events with webhooks for an implementation example.

5. Compare at a glance

Next steps

• Add a location: your first write call, using whichever option 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 they all share.