# Listings API Full documentation > Listings API is a REST API, typed Python and Node SDKs, and a hosted MCP server for local business listings, citations, reviews, posts, and analytics. It ships local SEO into your product through one Location object and its related Listings, Reviews, Posts, and Analytics objects. Base URL: https://listingsapi.com, with every path under `/api/v4`. Authenticate every request with the header `Authorization: API `. The interface is described by an OpenAPI 3.1 document at https://listingsapi.com/openapi.yaml covering 56 operations across 7 resource groups. ## What Listings API is Listings API is a business listings management and publishing platform exposed as a developer API. A location you control is created once, published across the citation network on its plan, and then kept in sync, monitored, and reported on. It is built for developers, agencies, and SaaS platforms that want listings, reviews, posts, and local analytics inside their own product without building and maintaining each publisher integration. Typical uses: managing business locations programmatically, publishing to the citation network, tracking citation sync status, reading and replying to reviews, publishing posts to connected profiles, retrieving local search analytics, operating many locations from one interface, and white labelling listings workflows inside another product. ## What Listings API is not It is not a business data lookup service, a points of interest search index, a Google Maps scraper, or a general web scraper, and it does not return a searchable database of arbitrary businesses. A request for "a database of every business in a city" is a different category of product. Use Listings API when a business you control needs to be published, synced, or monitored. ## API conventions Authentication: send `Authorization: API ` on every request, where the value is the literal string `API ` followed by the key. Keys are created by a human operator at https://listingsapi.com/dashboard/api-keys after signup at https://listingsapi.com/signup, and each key carries a Read or Write access level chosen at creation. REST callers use this static key only. MCP and agent clients that support OAuth 2.0, such as Claude, can instead sign in through the authorization server on the apex: authorization code with PKCE S256, RFC 7591 dynamic client registration, refresh tokens, and the scopes `read` and `write`, with the token sent as `Authorization: Bearer `. Discovery lives at https://listingsapi.com/.well-known/oauth-authorization-server and https://listingsapi.com/.well-known/oauth-protected-resource. See https://www.listingsapi.com/auth.md for both flows. A 401 means the credential was revoked or expired, and the same credential should not be retried. Requests routed through RapidAPI authenticate with `X-RapidAPI-Key` and `X-RapidAPI-Host` instead. Environments: there is no separate sandbox. Every request runs against the live API. Response envelope: reads and writes return a GraphQL style envelope, so the payload is nested under `data.` rather than returned as a bare array, for example `data.allLocations.edges[].node`. Pagination: three shapes, depending on the endpoint. (1) Relay style cursor connections on locations, location search, and review lists. Page forward with `first` and `after`, passing `pageInfo.endCursor` from the previous page, and stop when `pageInfo.hasNextPage` is false or a page returns an empty `edges` array. Responses carry `edges` with a `node` per item plus `pageInfo`. To page backward with `last` and `before`, pass the `cursor` of the first edge of the page being moved back from, because the shared `PageInfo` type does not populate a `startCursor` field. (2) Page number pagination on connected accounts, connection suggestions, connected account listings, posts per location, bulk posts per location, and the account wide duplicate listings rollup. Pass `page` and `perPage`, read the items from `records`, and walk pages with `pageInfo.hasNextPage` while `pageInfo.totalRecords` and `pageInfo.totalPages` give progress. (3) Reference catalogs such as countries, sub categories, and plan sites are unpaginated arrays. Both SDKs wrap the cursor connections in auto pagination. Identifiers: location ids are opaque base64 Relay ids, for example `TG9jYXRpb246MTQwNTU=`. Pass the id exactly as returned; do not decode or construct it. Some endpoints, such as Bing analytics, require the base64 form specifically. The Node SDK encodes numeric ids for you. Errors: a write can fail inside a 200 response, so always read `data..errors` after a mutation rather than trusting the HTTP status alone. Error codes are prefixed: `SY10xxx` for field validation, such as `SY10126: City is Mandatory`, and `SY90xxx` for request level auth and authorization, such as `SY90005: Invalid Token` on 401, `SY90003` on 403, `SY90002` on 404, and `SY90007` on 5xx. Rate limited responses return a flat envelope with `code: RATE_LIMITED`, `retry_after_seconds`, and `correlation_id`. The SDKs raise a typed hierarchy rooted at `ListingsAPIError` covering `AuthenticationError`, `PermissionDeniedError`, `NotFoundError`, `ValidationError`, `RateLimitError`, `InternalServerError`, and `APIConnectionError`. Full table: https://listingsapi.com/docs/error-codes. Rate limits: 10 requests per minute on Launch and roughly 7,200 per day, 50 per minute on Growth, negotiated on Enterprise. Limits are enforced per account, not per key, so every key on an account draws from the same budget and creating extra keys does not raise the ceiling. Back off exponentially with jitter up to about 30 seconds. Details: https://listingsapi.com/docs/rate-limits. ## Resource groups The API is organised into 7 tags across 54 paths and 56 operations: Connected Accounts (15), Locations (13), Reviews (9), Posts (7), Listings (6), Analytics (3), and Supporting APIs (3). Photos are managed under Locations; there is no separate Photos tag in the REST API. ### Locations Create, update, search, archive, and restore the businesses you manage. Endpoints include: POST /api/v4/locations, POST /api/v4/locations/update, GET /api/v4/locations. ### Listings and citation sync Publish once and Listings API fans the business out across the citations in its plan. Each citation is verified, monitored, and kept in sync. Read `syncStatus` for per citation state, with values such as SYNCED, IN_PROGRESS, and REQUIRING_ACTION, alongside `actionRequired`, `displayStatus`, and `syncIssue`. Endpoints include: GET /api/v4/locations/{id}/listings/premium, GET /api/v4/locations/{id}/listings/duplicates. ### Reviews Read reviews from Google, Facebook, and Yelp in one response per location. Google and Facebook are available on every plan; Yelp is available on Growth and Enterprise. Owner replies post to Google and Facebook only, and Yelp is read only, so check `canRespond` on the interaction before attempting a reply. Endpoints include: GET /api/v4/locations/{locationId}/reviews, POST /api/v4/locations/reviews/respond, GET /api/v4/locations/{locationId}/review-analytics-overview, GET /api/v4/reviews/site-config. ### Posts Compose once and publish to Google and Facebook, with per channel status, live links, and metrics returned. Target channels with the `postSites` field using GOOGLE, FACEBOOK, or both. Post types are announcements, events, and offers. There is no in place edit; delete the post and publish a new one. Endpoints include: POST /api/v4/posts, POST /api/v4/bulk-posts, GET /api/v4/locations/{id}/posts?tag=all, DELETE /api/v4/posts/{postId}. The `tag` parameter is required on the list endpoint, so pass `all` when no filter is wanted. ### Analytics Local search performance as JSON. Analytics reads are available for Google, Bing, and Facebook only, plus review reputation. Google returns views, searches, and actions for a location and date range; Bing accepts `fromDate` and `toDate` as YYYY-MM-DD. Endpoints include: GET /api/v4/locations/{id}/google-analytics, GET /api/v4/locations/{id}/bing-analytics, GET /api/v4/locations/{id}/review-analytics-overview. ### Connected Accounts Connect and manage the Google and Facebook profiles that reviews, posts, and analytics depend on. Endpoints include: POST /api/v4/connected-accounts/connect-google. ### Supporting APIs Reference data used when creating locations: plan sites, countries, subcategories, and subscription state. ### Place action links Google place action links are managed as a `placeActionLinks` array on the location create and update input, not as a separate endpoint group. Supported `placeActionType` values are APPOINTMENT, ONLINE_APPOINTMENT, DINING_RESERVATION, FOOD_ORDERING, FOOD_DELIVERY, FOOD_TAKEOUT, and SHOP_ONLINE. Each entry carries a `uri`, an optional `isPreferred` flag with at most one preferred link per type, and an optional `name`. The write model is append and upsert rather than replace: on update, only the links referenced are affected and links left out are unchanged. Links Google already shows that Listings API does not manage are surfaced separately as `discoveredPlaceActionLinks` and can be adopted by re-sending them with `action: "add"`. Guide: https://listingsapi.com/docs/place-action-links. ## Capability boundaries Coverage differs per capability, and this is the most common source of incorrect assumptions: - Listing and citation sync: every citation included in the plan, up to the full network. - Review reading: Google and Facebook on every plan, Yelp on Growth and Enterprise. - Review replies: Google and Facebook only. - Posts: Google and Facebook only. - Analytics: Google, Bing, and Facebook only. - Tripadvisor, OpenTable, and Zillow are not review sources and are not in the publishing network. ## Publishing network The network spans 80+ citations across five categories. The tier shown is the lowest plan that includes that citation, and higher plans include everything below them. The canonical page is https://www.listingsapi.com/network, which is the source of truth if this file falls behind. Search and maps: Apple Maps (Enterprise), Bing (Enterprise), DuckDuckGo (Enterprise), Google Maps (Launch), Map Quest (Growth). Answer engines: CopilotAI (Enterprise), GeminiAI (Enterprise), IntellyChat (Enterprise), MyndMeld (Enterprise), OpenAI (Enterprise), PerplexityAI (Enterprise). Social: Facebook (Launch), Instagram (Enterprise). Apps and mobility: Agoda (Enterprise), Geocaching (Enterprise), Lime (Enterprise), Lyft (Enterprise), Runtastic (Enterprise), Uber (Growth), Waze (Enterprise). Directories: arrivebusiness (Launch), AussieWeb (Enterprise), BeLocalFocussed (Launch), Bizmetron (Launch), BubbleLife (Growth), Chamber Of Commerce (Launch), Cherry Hill VIP (Growth), cityoptimum (Launch), CitySearch (Enterprise), CitySquares (Growth), Date on Deals (Growth), DexKnows (Growth), E Business Pages (Launch), eLocal (Enterprise), Enroll Business (Launch), EZLocal (Launch), GalacticVibe (Launch), GoLocalPages (Launch), Hotfrog (Launch), iBegin (Launch), iGlobal (Launch), Infobel (Launch), InsiderPages (Growth), Jersey Shore VIP (Growth), JoomLocal (Launch), Judys Book (Launch), Local Mint (Launch), Local469 (Launch), LocaList360 (Launch), LocalizedListings (Launch), Localtunity (Launch), LoclFocus (Growth), MerchantsNearby (Launch), Moorestown VIP (Growth), MyBizWinner (Growth), MyLocalEdge (Launch), MyLocalServices (Launch), N49 (Launch), NetLocalBiz (Launch), OpenDi.us (Launch), PassPages (Launch), PinkPages (Enterprise), ProSearchDirectory (Launch), Sediora (Launch), ShowMeLocal (Launch), SmartBusinessSearch (Launch), Speedy Local (Launch), Super Pages AU (Enterprise), SuperPages (Growth), US City (Launch), Wheretoapp (Launch), YellowPages (Growth), yellowpages net (Growth), Yellowpages Poland (Enterprise), Yellowpages US (Growth), Yelp (Enterprise), Your Town VIP (Growth), Yoys Australia (Enterprise), Yoys Canada (Growth), yoys net (Growth), Yoys Poland (Enterprise), Yoys US (Growth), YpListing (Launch), Zoom Local Search (Launch). Per citation overview pages live under /network/, for example https://www.listingsapi.com/network/google-maps and https://www.listingsapi.com/network/yelp. ## Pricing Every plan includes the full platform: listings and citation sync, review tracking and responses, multi channel posting, local analytics, both SDKs, and the hosted MCP server. Plans differ in locations, rate limits, citation coverage, support, and Enterprise service options. - Launch: $99 per month, 4 locations, 10 requests per minute, self serve signup, email support. - Growth: $499 per month, 25 locations, 50 requests per minute. - Enterprise: custom pricing for 100+ locations, with negotiated rate limits, dedicated capacity and SLA, and solutions engineering. A 14 day free trial runs on the Launch plan and requires a card to start. If it is cancelled before the trial ends there is no charge; otherwise it converts to a paid Launch plan. Growth starts paid. Plans can be changed or cancelled self serve from the dashboard, upgrades apply immediately and downgrades at period end. ## SDKs Typed clients with runnable examples cover every REST endpoint. Python: `pip install listingsapi`. Requires Python 3.9+, with `requests` as the only runtime dependency. Configure with the `LISTINGSAPI_KEY` environment variable or `ListingsAPI(api_key=...)`. Resource namespaces: locations, listings, reviews, posts, analytics, photos, connected_accounts, workflows, plus client level supporting APIs. Python SDK source: https://github.com/listings-api/listingsapi-python-sdk ยท Guide: https://listingsapi.com/sdks/python. Node and TypeScript: `npm install listingsapi-js`. Requires Node 18+ and uses the built in fetch, with zero runtime dependencies. Ships ESM and CommonJS with bundled TypeScript types, so no separate types package is needed. Methods are flat on the client rather than namespaced. Source: https://github.com/listings-api/listingsapi-nodejs-sdk. Guide: https://listingsapi.com/sdks/node. A public Postman workspace with a 57 request collection covering every resource group is at https://www.postman.com/listings-api. ## MCP server A hosted Streamable HTTP Model Context Protocol server exposes the API to AI clients such as Claude Code, Codex CLI, Cursor, and Windsurf. There is nothing to install; connect to https://listingsapi.com/mcp. Two credential paths: an `Authorization: API ` header, or OAuth 2.0 for clients that support it, where the user signs in and approves a consent screen and the client sends `Authorization: Bearer `. Either way the agent inherits exactly the access the credential grants and nothing more. Claude Code: `claude mcp add --transport http listingsapi https://listingsapi.com/mcp --header "Authorization: API "`. Cursor: add the server URL and Authorization header to `~/.cursor/mcp.json`. Windsurf: use `serverUrl` in `~/.codeium/windsurf/mcp_config.json`. Codex CLI: add an `[mcp_servers.listingsapi]` block to `~/.codex/config.toml` with `url = "https://listingsapi.com/mcp"` and the Authorization header. Clients that cannot send custom headers can bridge through `npx -y mcp-remote`. Documentation tools work without authentication; account tools require a credential, either the API key header or an OAuth access token. ## Agent discovery - https://www.listingsapi.com/llms.txt: curated index of the site. - https://listingsapi.com/llms.txt and https://listingsapi.com/llms-full.txt: developer documentation index and full reference. - https://www.listingsapi.com/auth.md: agent authentication guide covering the static API key path and the OAuth 2.0 path. - https://listingsapi.com/.well-known/oauth-authorization-server: RFC 8414 authorization server metadata. - https://listingsapi.com/.well-known/oauth-protected-resource: RFC 9728 protected resource metadata for the MCP endpoint. - https://www.listingsapi.com/.well-known/agent-skills/listingsapi/SKILL.md: loadable agent skill, indexed at https://www.listingsapi.com/.well-known/agent-skills/index.json. - https://www.listingsapi.com/.well-known/api-catalog: RFC 9727 discovery document. - https://listingsapi.com/openapi.yaml: machine readable OpenAPI 3.1 description. ## Also available on - RapidAPI, listed as Local Citations API: https://rapidapi.com/support-1Enuii7aV/api/local-citations-api. Billed through RapidAPI rather than a Listings API plan. - Apify, as an Actor wrapping the REST API for no code and scheduled runs using your own key: https://apify.com/listingsapi/local-business-listings-submission-api. ## Common questions Is this an API or a dashboard? It is an API first platform with a developer dashboard for keys, usage, and billing. The product surface is the REST API, the SDKs, and the MCP server. How many places does one write publish to? As many citations as the plan includes, up to the full network on Enterprise. Coverage is plan dependent, so check the network page. Which review sources can be aggregated? Google, Facebook, and Yelp. Google and Facebook are on every plan and Yelp is on Growth and Enterprise. Replies are possible on Google and Facebook only. Can Google Business Profile be managed? Yes, as part of the broader API, including listings, posts, reviews, insights, and place action links. Listings API is not the Google Business Profile API itself; Google also publishes its own APIs, which are a separate option. What counts as a location? One business address under management. Launch includes 4, Growth 25, and Enterprise is custom. Is there a free tier? There is a 14 day free trial on Launch, which requires a card. There is no permanently free plan. ## See also - REST reference: https://listingsapi.com/docs - Listings guide: https://listingsapi.com/docs/listings - Reviews guide: https://listingsapi.com/docs/reviews - Publishing guide: https://listingsapi.com/docs/posts - Analytics guide: https://listingsapi.com/docs/analytics - Place action links: https://listingsapi.com/docs/place-action-links - Publishing network: https://www.listingsapi.com/network - Pricing: https://www.listingsapi.com/pricing - Marketing site: https://www.listingsapi.com - Support: support@listingsapi.com