/api/v4/locations/{locationId}/listings/premiumGet premium listings for a location
Returns the sync status of every publisher directory in a location's plan.
Parameters
Path
| Name | Type | Required | Description |
|---|---|---|---|
| locationId | string | required | Location to read. Accepts a base64-encoded Relay ID (e.g. `TG9jYXRpb246MTgwMDI4OQ==`) or a raw numeric location ID. |
Query
| Name | Type | Required | Description | Default |
|---|---|---|---|---|
| listingType | string | required | Which listing tier to return: `premium` for the plan's premium directory listings, or `additional` for additional/free listings. | — |
Responses
200Array of listings with per-directory sync status.
{ "data": { "listingsForLocation": [ { "id": "TGlzdGluZzoxMDQ0Njg3MjM=", "databaseId": "104468723", "site": { "id": "U2l0ZTox", "databaseId": "1", "name": "Google Maps", "url": "maps.google.com", "syScore": "100" }, "syncStatus": "REQUIRING_ACTION", "displayStatus": "Connect your account to sync the listing", "actionRequired": true, "listingUrl": null, "connectedAccountId": null, "lastUpdate": "2026-07-06T18:33:28Z", "indexStatus": false, "syncIssue": null, "verified": false }, { "id": "TGlzdGluZzoxMDQ0Njg3MTQ=", "databaseId": "104468714", "site": { "id": "U2l0ZToxODA=", "databaseId": "180", "name": "Bing", "url": "www.bing.com", "syScore": "97" }, "syncStatus": "IN_PROGRESS", "displayStatus": "Information submitted to partner; awaiting response", "actionRequired": false, "listingUrl": null, "connectedAccountId": null, "lastUpdate": "2026-07-06T18:33:35Z", "indexStatus": false, "syncIssue": null, "verified": false }, { "id": "TGlzdGluZzoxMDQ0Njg3Mjc=", "databaseId": "104468727", "site": { "id": "U2l0ZTozODc=", "databaseId": "387", "name": "BeLocalFocussed", "url": "belocalfocussed.com", "syScore": "80" }, "syncStatus": "SYNCED", "displayStatus": "Synced", "actionRequired": false, "listingUrl": "https://belocalfocussed.com/jenny-home-26x0ffkd0e", "connectedAccountId": null, "lastUpdate": "2026-07-06T18:33:30Z", "indexStatus": false, "syncIssue": null, "verified": false }, { "id": "TGlzdGluZzoxMDQ0Njg3MDk=", "databaseId": "104468709", "site": { "id": "U2l0ZTozMDE=", "databaseId": "301", "name": "Local Mint", "url": "localmint.com", "syScore": "69" }, "syncStatus": "FAILED", "displayStatus": "Partner experiencing issues; awaiting response", "actionRequired": false, "listingUrl": null, "connectedAccountId": null, "lastUpdate": "2026-07-06T18:34:03Z", "indexStatus": false, "syncIssue": "Publisher requires website URL", "verified": false } ] }}401Unauthenticated, missing or invalid API key.
429Rate limit exceeded. Retry after the `Retry-After` header value.
Returns the sync status of every publisher directory included in a location's plan. Each record pairs a site (directory metadata) with a syncStatus and a human-readable displayStatus. The example above is trimmed from the live response for Jenny Home (which returns 30+ directories) to show one record in each of the common states.
The listingType query parameter is required: pass listingType=premium for the plan's premium directories (shown here) or listingType=additional for additional/free listings.
Use case: a listings health dashboard
Fetch the premium listings for a location and group by syncStatus to show coverage at a glance, how many directories are live, in flight, or blocked. Surface listingUrl for SYNCED rows so users can click through to the live listing, and read displayStatus/syncIssue for anything that isn't synced (e.g. Publisher requires website URL).
Use case: surface the "connect your account" blockers
Filter for actionRequired: true to build the owner's to-do list. In the live data, Google Maps, Facebook, and Waze come back REQUIRING_ACTION with displayStatus: "Connect your account to sync the listing", these need an OAuth connection before they can sync. Route the owner to the corresponding connect flow, then re-poll this endpoint to watch the status advance.
syncStatus values: AVAILABLE (ready to sync, not started), IN_PROGRESS (submitted to partner, awaiting response), PENDING_APPROVAL (awaiting partner approval), SYNCED / COMPLETED (live; listingUrl populated), REQUIRING_ACTION (owner action needed, see displayStatus), FAILED (sync failed; see syncIssue), CANNOT_SUBMIT (submission not possible).
This is a per-location list subject to the account rate limit, on 429, retry after the Retry-After header rather than re-polling immediately.
curl -X GET 'https://listingsapi.com/api/v4/locations/<locationId>/listings/premium?listingType=<listingType>' \ -H "Authorization: API $LISTINGSAPI_KEY"