Standorte verwalten
Wir gratulieren zur Erstellung einer Yext-App! Damit ist der erste Schritt zur Nutzung der API getan. Durch die Bereitstellung präziser Standortdaten auf den wichtigsten Websites lassen sich Sichtbarkeit und Auffindbarkeit eines Unternehmens erheblich verbessern. Legen wir also los!

Standort anlegen

Um einen Standort zu erstellen, müssen Sie eine POST-Anfrage mit folgender URL senden:

POSThttps://api.yext.com/v2/accounts/me/locations?api_key=API_KEY&v=YYYYMMDD

Anschließend können Sie das Standort-Objekt in Form von Nutzdaten senden. Wenn Sie einen Standort erstellen, müssen Sie immer die Werte für die Felder id (ID), name (Name), address (Adresse), city (Stadt), state (Bundesstaat bzw. -land), zip (Postleitzahl), phone (Telefonnummer) und categoryIds (Kategorie-IDs) eintragen. Alle anderen Felder sind optional. Denken Sie daran, dass das Feld id für jeden Standort in Ihrem Konto eindeutig sein muss.

Probieren wir es mal aus:

POSThttps://api.yext.com/v2/accounts/me/locations?api_key=API_KEY&v=YYYYMMDD

Anforderungsinhalt:
{
    "id": "TestStandort1",
    "locationName": "Ihr erster Test-Standort",
    "address": "Kaiserstraße 123",
    "city": "Berlin",
    "state": "Berlin",
    "zip": "12345",
    "countryCode": "DE",
    "language": "de",
    "phone": "03011223344",
    "categoryIds": [
      "3",
      "886"
    ]
 }
Nun sollten Sie eine Erfolgsmeldung und eine Antwort mit der ID des Standorts erhalten:
{
 „meta“: {
   „uuid“: „3f924dc9-b3ba-4561-aa70-93add5c2c0e3“,
   „errors“: []
 },
 „response“: {
   „id“: „TestStandort1“
 }
}

Standort abrufen

Sie können die Erstellung des Standorts auch durch das Senden dieser GET-Anfrage bestätigen:

GEThttps://api.yext.com/v2/accounts/me/locations/TestLocation1?api_key=API_KEY&v=YYYYMMDD

Sie sollten eine ähnliche Antwort wie die untenstehende erhalten.
{
 „meta“: {
   „uuid“: „664ad06d-51d3-46d6-aaef-dd0c41a383ee“,
   „errors“: []
 },
 „response“: {
   „id“: „TestStandort1“,
   „timestamp“: 1476299272562,
   „accountId“: „469411“,
   „locationName“: „Ihr erster Teststandort“,
   „address“: „205 Main St“,
   „city“: „New York“,
   „state“: „NY“,
   „zip“: „10001“,
   „countryCode“: „US“,
   „language“: „en“,
   „suppressAddress“: false,
   „phone“: „2125555765“,
   „isPhoneTracked“: false,
   „categoryIds“: [
     „3“,
     „886“
   ],
   „featuredMessage“: „Rufen Sie heute an“,
   „folderId“: „0“,
   „locationType“: „STANDORT“
 }
}

Versuchen Sie jetzt, einen zweiten Standort mit derselben id zu erstellen. Sie sollten folgende Fehlermeldung erhalten:
{
 "meta": {
   "uuid": "34ad7bfd-ecc2-4e8c-8ecb-23f7e743cced",
   "errors": [
     {
       "code": 2017,
       "type": "FATAL_ERROR",
       "message": "Location with id TestLocation1 already exists"
     }
   ]
 },
 "response": {}
}
Standort-ids müssen für jeden Standort eindeutig sein. Der Code oben zeigt ein Beispiel für einen FATAL_ERROR (schwerwiegenden Fehler).

API-Fehler

Yext überprüft alle Ihre Anfragen und kann einen von drei Fehlertypen ausgeben: FATAL_ERROR (schwerwiegender Fehler), NON_FATAL_ERROR (leichter Fehler) und WARNING (Warnung). Sie sollten alle Fehlerquellen ermitteln und die nötigen Änderungen vornehmen.

FATAL_ERRORs verhindern, dass die API-Anfrage verarbeitet wird. Die Verwendung einer doppelten Standort-id ist ein Beispiel für einen FATAL_ERROR. Jeder FATAL_ERROR muss behoben werden, bevor die Anfrage bearbeitet werden kann. Um den FATAL_ERROR im Beispiel zu beheben, ändern Sie die id in Ihrer Anfrage und senden Sie sie erneut.

NON_FATAL_ERRORs sind Fehler, durch die ein Objekt in einer Liste oder ein Feld in einem Objekt abgelehnt wird. Ob wir die gesamte Anfrage ablehnen, hängt davon ab, ob die validation (Überprüfung) der Anfrage strict (streng) oder lenient (mild) ist.

Weil der Überprüfungsmodus standardmäßig strict ist, sorgen NON_FATAL_ERRORs und FATAL_ERRORs dafür, dass eine API-Anfrage fehlschlägt, wenn kein Wert für die validation festgelegt wurde. Ändern Sie den Überprüfungsmodus zu lenient, indem Sie der Anfrage-URL validation=lenient als Parameter hinzufügen. In diesem Modus verhindern nur FATAL_ERRORs, dass eine API-Anfrage bearbeitet wird, NON_FATAL_ERRORs nicht. Zum Beispiel können Sie uns eine Reihe von Speisekarten für Standorte senden. Wenn der Überprüfungsmodus lenient ist und bei einer Speisekarte ein NON_FATAL_ERROR auftritt, speichern wir diese Speisekarte nicht, aber die anderen. Wenn der Überprüfungsmodus strict ist, wird die ganze Anfrage abgelehnt und wir speichern keine der Speisekarten. Wir empfehlen, bei der Produktion validation=lenient und bei Tests und F&E-Aktivitäten validation=strict zu verwenden.

Der letzte Fehlertyp ist WARNING. WARNINGs erscheinen, wenn ein Feld die Überprüfung durch Yext besteht, aber der Inhalt als möglicherweise schlechte Daten gemeldet wird, die unsere Publisher nicht annehmen werden. WARNINGs verhindern nicht, dass eine API-Anfrage bearbeitet wird.

Im milden Modus werden WARNINGs und NON_FATAL_ERRORs in der Fehler-Liste im Meta-Abschnitt angezeigt, aber wir führen immer noch so viel wie möglich von der Anfrage aus.

Standort aktualisieren

Sie haben erfolgreich einen Standort erstellt, aber nun wollen Sie womöglich vorhandene Felder bearbeiten oder Inhalte mit neuen Feldern hinzufügen. Dazu müssen Sie folgende PUT-Anfrage senden:

PUThttps://api.yext.com/v2/accounts/me/locations/TestLocation1?api_key=API_KEY&v=YYYYMMDD

Anschließend können Sie das Standort-Objekt in Form von Nutzdaten senden.

Das Yext-System aktualisiert ausschließlich die Felder, die Sie im Standort-Objekt angeben, und sonst nichts. Das Schöne an diesem Verfahren ist, dass Sie nur die Felder absenden müssen, die sich geändert haben.

Versuchen wir mal, nur die „Mein Highlight“-Nachricht für Ihren ersten Test-Standort zu aktualisieren:

PUThttps://api.yext.com/v2/accounts/me/locations/TestLocation1?api_key=API_KEY&v=YYYYMMDD

Anforderungsinhalt:
{
    "featuredMessage": "Tolle Angebote warten auf Sie!"
}
Nun sollten Sie eine Erfolgsmeldung und eine Antwort mit der id des Standorts erhalten:
{
 „meta“: {
   „uuid“: „5ac9cdc5-e0c6-4de4-b4da-e99ffef027fb“,
   „errors“: []
 },
 „response“: {
   „id“: „TestStandort1“
 }
}
Geben Sie eine weitere „Get Locations“-Anfrage aus und beachten Sie, wie nur die „Mein Highlight“-Nachricht aktualisiert wurde und sich die anderen Felder nicht verändert haben.

Versuchen wir jetzt, das Feld „featuredMessage“ („Mein Highlight“-Nachricht) zu aktualisieren und neue Inhalte für die Felder „tollFreePhone“ (Nummer für gebührenfreie Anrufe), „hours“ (Geschäftszeiten) und „holidayHours“ (Geschäftszeiten an Feiertagen) anzugeben. Im Folgenden finden Sie die Geschäftszeiten für diesen Standort.
  • Sonntag: 24 Stunden geöffnet
  • Montag: 9:00 bis 12:00 Uhr und 14:00 bis 17:00 Uhr
  • Dienstag: 9:00 bis 17:00 Uhr
  • Mittwoch: geschlossen
  • Donnerstag: 9:00 bis 17:00 Uhr
  • Freitag: 9:00 bis 17:00 Uhr
  • Samstag: 10:00 bis 16:00 Uhr
An manchen Feiertagen gelten für diesen Standort andere Geschäftszeiten:
  • 26. November 2020: 9:00 bis 15:00 Uhr
  • 27. November 2020: 24 Stunden geöffnet
  • 24. Dezember 2020: 9:00 bis 18:00 Uhr
  • 25. Dezember 2020: geschlossen
  • 1. Januar 2021: normale Öffnungszeiten
PUThttps://api.yext.com/v2/accounts/me/locations/TestLocation1?api_key=API_KEY&v=YYYYMMDD

Anforderungsinhalt:
{
    "featuredMessage": „Kommen Sie vorbei, um sich unsere Updates anzusehen!“,
    "tollFreePhone": 8008735209,
    "hours": "1:00:00:00:00,2:9:00:12:00,2:14:00:17:00,3:9:00:17:00,4:closed,5:9:00:17:00,6:9:00:17:00,7:10:00:16:00",
    "holidayHours": [
        {
            "date": "2020-11-26",
            "hours": "9:00:15:00",
            "isRegularHours": false
        },
        {
            "date": "2020-11-27",
            "hours": "0:00:0:00",
            "isRegularHours": false
        },
        {
            "date": "2020-12-24",
            "hours": "9:00:18:00",
            "isRegularHours": false
        },
        {
            "date": "2020-12-25",
            "hours": "",
            "isRegularHours": false
        },
        {
            "date": "2021-01-01",
            "isRegularHours": true
        }
    ]
}
Wie zuvor enthält der Hauptteil der Antwort die id (ID) des Standorts.
{
 "meta": {
   "uuid": "2d56b310-f4ba-4648-a447-395a3cdba67f",
   "errors": []
 },
 "response": {
   "id": "Teststandort1"
 }
}
Zum Schluss wollen wir Ihren Standort als geschlossen kennzeichnen. Hierzu hängen Sie „- closed“ an Ihren locationName (Standortnamen) an,setzen alle hours (Geschäftszeiten) auf „closed“ (geschlossen)und die Kennzeichnung isClosed (ist geschlossen) auf „true“ (wahr).Wenn Sie möchten, können Sie außerdem das closeDate(Schließdatum) angeben. Sehen wir uns einmal das folgende Beispiel an.

PUThttps://api.yext.com/v2/accounts/me/locations/TestLocation1?api_key=API_KEY&v=YYYYMMDD

Anforderungsinhalt:
{
    "locationName": "Teststandort – geschlossen",
    "closed": {
        "isClosed": true,
        "closeDate": "2025-09-29"
    },
    "hours": "1:geschlossen"
}

Senden Sie ruhig noch mehr API-Anfragen und aktualisieren Sie noch mehr Felder. Nehmen Sie sich dann einen Moment Zeit, um zu sehen, wie viel Sie mit ein paar API-Anfragen geschafft haben!