List interactions for a location — Listings API

Parameters

Path

Name	Type	Required	Description
locationId	string	required	Location ID, a raw numeric database ID (e.g. `1800289`) or its Base64-encoded Relay ID (e.g. `TG9jYXRpb246MTgwMDI4OQ==`).

Query

Name	Type	Required	Description	Default
tag	string	optional	Filter by a location tag.	—
siteUrls	string	optional	JSON-encoded array of publisher hostnames to include, e.g. `["maps.google.com","yelp.com"]`.	—
startDate	string	optional	Start of the date-range filter (YYYY-MM-DD).	—
endDate	string	optional	End of the date-range filter (YYYY-MM-DD).	—
searchString	string	optional	Full-text search across interaction content.	—
category	string	optional	Single interaction category, e.g. `REVIEW`.	—
categories	string	optional	JSON-encoded array of interaction categories.	—
ratingFilters	string	optional	JSON-encoded array of star ratings to include, e.g. `[3,4]`.	—
ratingFilter	integer	optional	Single star rating to filter by.	—
responseStatus	string	optional	JSON-encoded response-status filter. Values: `RESPONDED`, `PENDING`.	—
sortOrder	string	optional	JSON-encoded sort order. Values: `NEWEST_FIRST`, `OLDEST_FIRST`, `LAST_RESPONDED`.	—
first	integer	optional	Number of records to return from the beginning (newest first). Defaults to 20 when omitted, the endpoint always returns a single page, never the whole history.	—
after	string	optional	Cursor to page forward from. Pass `pageInfo.endCursor`, or equivalently the `cursor` of the last edge in the previous page.	—
last	integer	optional	Number of records to return from the end.	—
before	string	optional	Cursor to page backward from, used with `last`. Pass the `cursor` of the first edge of the page you are moving back from. `pageInfo` carries no `startCursor` field, so the edge cursor is the value to use.	—

Responses

200Paginated interactions result. `data.interactions` holds the connection.

{
  "data": {
    "interactions": {
      "pageInfo": {
        "hasNextPage": true,
        "hasPreviousPage": false,
        "endCursor": "SW50ZXJhY3Rpb246MV8xNTU0MjQzMDczMDM2LTllMjZkMmE4LWE2ZWQtNDJlYS04NDU0LTQ3ZDFjOTJlYTg0MQ=="
      },
      "edges": [
        {
          "node": {
            "id": "9e26d2a8-a6ed-42ea-8454-47d1c92ea841",
            "source": "maps.google.com",
            "content": "nice place for family together",
            "authorName": "vaibhav nakate",
            "rating": 5,
            "date": "2019-04-02T22:11:13.036997+00:00",
            "category": "Review",
            "type": "Review",
            "responded": false,
            "responseCount": 0,
            "canRespond": true,
            "permalink": "https://maps.google.com/maps?cid=..."
          },
          "cursor": "SW50ZXJhY3Rpb246MV8xNTU0MjQzMDczMDM2LTllMjZkMmE4LWE2ZWQtNDJlYS04NDU0LTQ3ZDFjOTJlYTg0MQ=="
        }
      ],
      "totalCount": 425
    }
  }
}

401Unauthenticated, missing or invalid API key.

429Rate limit exceeded. Retry after the `Retry-After` header value.

Returns reviews and social interactions for a location using cursor-based pagination. Results default to the most recent first. The connection lives at data.interactions and contains edges[].node (see the interaction attributes reference), an endCursor in pageInfo, and a totalCount.

totalCount is the number of interactions matching your filters across the whole result set, not the number returned in this page. Use it to size a backfill or to check your own tally: a location with totalCount: 450 read at first=50 takes 9 requests, and the counts should add up to 450 when you reach the end. Omitting first returns 20 records, so a single call is never the full history.

Use case: a per-store reviews inbox

To build a reviews inbox for one location, page forward with first and after: request first=25, then pass the response's pageInfo.endCursor as after on the next call. Every edge also carries its own cursor, and the last edge's cursor is that page's endCursor, so either value works as after. Stop when hasNextPage is false or when a page comes back with an empty edges array, test both, because a page boundary that lands exactly on the oldest review is followed by one final empty page. Layer on responseStatus=["PENDING"] to show only reviews still awaiting an owner reply, or ratingFilters=[1,2] to triage negative reviews first. From each node, the id is what you pass to Respond to an interaction, and canRespond tells you whether that source accepts owner replies.

Use case: incremental sync

To keep a local mirror in sync, filter by startDate/endDate and sort with sortOrder=["NEWEST_FIRST"], persisting the highest date you have seen. Note this is a paginated, rate-limited endpoint, honor the Retry-After header on a 429 and avoid re-fetching the full history on every run.

Google Maps and Facebook are available on every plan. Yelp is available on the Growth and Enterprise plans. JSON-encoded filters (siteUrls, categories, ratingFilters, responseStatus, sortOrder) are passed as URL-encoded JSON strings.