Listings APIListings API
Anmelden
GET/api/v4/locations/search

Standorte suchen

Gibt eine Cursor-paginierte Liste von Standorten zurück, die zum Suchbegriff passen. Suchbar nach Name, Adresse oder Filial-ID.

Erfordert einen API-Schlüssel. Format des Headers und Schlüsselrotation finden Sie unter Authentifizierung.

Parameter

Query

NameTypErforderlichBeschreibungStandard
querystringoptionalSearch keyword matched against location name, street address, city, and store ID. Omit to page through every location.—
filterstringoptionalJSON-encoded filter object to narrow results (for example by approval status).—
firstintegeroptionalNumber of records to fetch, starting from the most recent.50
afterstringoptionalCursor to fetch records after (forward pagination). Pass the previous page's `pageInfo.endCursor`.—

Antworten

200Cursor-paginated list of matching locations.
Response
{  "data": {    "searchLocations": {      "edges": [        {          "cursor": "TG9jYXRpb246MTgwMDI4OQ==",          "node": {            "accountId": 12345,            "accountName": "owner@brightsmile-dental.com",            "addOns": [],            "additionalCategoryIds": [],            "additionalCategoryNames": [],            "additionalGbpSiteCategoryIds": [],            "additionalGbpSiteCategoryNames": [],            "additionalInfo": null,            "additionalPhones": [],            "aiAnalyticsEnabled": false,            "approved": "APPROVED",            "archivalScheduledAt": null,            "archived": false,            "archivedAt": null,            "bizUrl": null,            "bizUrlUtm": false,            "bookingUrl": null,            "businessHours": [],            "cancellationScheduledAt": null,            "categoryId": 15,            "city": "Austin",            "clientName": "owner@brightsmile-dental.com",            "contentPreferredLanguage": "ENGLISH",            "countryCode": "1",            "countryIso": "US",            "createErrors": [],            "createdDate": "July 06, 2026",            "customAttributes": [],            "databaseId": 1800289,            "defaultAgencyTag": "ownerbrightsmiledentalcom",            "description": "This is a standalone duplex house. A comfortable, private residence located in the Bouldin Creek neighborhood of Austin.",            "discoveredPlaceActionLinks": [],            "enabledSiteIds": [],            "facebookUrl": null,            "franchise": false,            "googleAdsPhone": null,            "googleVerificationStatus": { "message": null, "status": "NOT_CONNECTED" },            "googleplusUrl": null,            "hideAddress": false,            "id": "TG9jYXRpb246MTgwMDI4OQ==",            "instagramUrl": null,            "isRestaurant": true,            "lastUpdatedDate": "July 06, 2026",            "latitude": "30.2711286",            "linkedinUrl": null,            "locationPhotos": [],            "longitude": "-97.7436995",            "managedServiceSiteBuckets": [],            "managedServiceSites": [],            "moreHours": [],            "name": "Jenny Home",            "offeringsUrl": null,            "ownerEmail": null,            "ownerName": null,            "package": "PREMIUM",            "paymentMethods": [],            "phone": "5125550142",            "pinterestUrl": null,            "placeActionLinks": [],            "planId": 3797,            "planName": "Launch",            "postalCode": "78701",            "primaryGbpSiteCategoryId": null,            "primaryGbpSiteCategoryName": null,            "publisherAttributes": [],            "reservationUrl": null,            "serviceArea": null,            "serviceItems": [],            "stateIso": "TX",            "stateName": "Texas",            "storeId": null,            "street": "600 Congress Ave, Suite 200",            "street1": null,            "subCategoryId": 1432,            "subCategoryName": "Restaurants",            "tagline": null,            "temporarilyClosed": false,            "tiktokUrl": null,            "toplineMessage": null,            "twitterUrl": null,            "uid": "3c92283c-6145-4a43-8a62-0c15fd712021",            "updatedAt": "2026-07-06T18:33:29.664Z",            "videos": [],            "voiceStatus": 3,            "yearOfIncorporation": null,            "youtubeUrl": null          }        }      ],      "pageInfo": {        "endCursor": "TG9jYXRpb246MTgwMDI4OQ==",        "hasNextPage": false,        "hasPreviousPage": false,        "total": 1      }    }  }}
401Unauthenticated, missing or invalid API key.
429Rate limit exceeded. Retry after the `Retry-After` header value.

Verwenden Sie diesen Endpunkt, um Standorte anhand eines Freitext-Suchbegriffs zu finden. Der Suchbegriff wird mit dem Standortnamen, der Straßenadresse, der Stadt und der Filial-ID abgeglichen, sodass eine einzelne Abfrage wie ?query=Jenny „Jenny Home“ findet, unabhängig davon, ob der Benutzer die Marke, eine Straße oder einen internen Filialcode eingegeben hat.

Anwendungsfall: Standortauswahl mit Suchvorschlägen während der Eingabe. Um ein Suchfeld „Ihre Standorte durchsuchen“ in einem Dashboard bereitzustellen, rufen Sie bei jedem Tastendruck GET /locations/search?query=<term>&first=10 auf (mit Entprellung) und stellen Sie edges[].node.name mit databaseId dar. Da der Knoten die vollständige Adresse, die Kategorie und den approved-Status enthält, können Sie ohne eine zweite Abfrage eine Ergebniszeile mit ausführlichen Informationen anzeigen.

Anwendungsfall: Abgleich mit Ihrem eigenen System. Um vor der Übermittlung einer Aktualisierung zu bestätigen, dass eine Filiale in Listings API vorhanden ist, suchen Sie nach Ihrem storeId-Wert; ein leeres edges-Array bedeutet, dass der Standort noch nicht erstellt wurde.

Paginierung und Fallstricke.

  • Die Ergebnisse werden anhand eines Cursors paginiert. Übergeben Sie pageInfo.endCursor aus der vorherigen Antwort als after, um die nächste Seite abzurufen, und beenden Sie den Vorgang, wenn hasNextPage gleich false ist. Beachten Sie, dass die Anzahl auf Seitenebene in pageInfo.total steht, nicht in totalCount.
  • Wenn Sie query weglassen, werden Ihre Standorte ungefiltert zurückgegeben (unter Berücksichtigung von first), wodurch Sie bequem das gesamte Konto seitenweise durchlaufen können.
  • Die Suche unterliegt demselben Ratenlimit wie die übrigen Anfragen des Kontos. Warten Sie bei 429 entsprechend der Angabe im Retry-After-Header, bevor Sie es erneut versuchen.

Für jeden passenden Standort werden placeActionLinks (die von Listings API verwalteten Google-Aktionslinks) und discoveredPlaceActionLinks (Links, die direkt im Google-Profil des Unternehmens gefunden wurden und noch nicht verwaltet werden) zurückgegeben. Siehe den Leitfaden zu Place Action Links.

Request
curl -X GET 'https://listingsapi.com/api/v4/locations/search' \  -H "Authorization: API $LISTINGSAPI_KEY"
Run in playground