Nutzung von Analytics
Sie haben erfolgreich einen Standort erstellt und seine Daten über unsere APIs an das Publisher-Netzwerk von Yext übermittelt. Jetzt fragen Sie sich vielleicht, wie viele Leute sich die zugehörigen Listings angesehen oder auf unserem Netzwerk nach Ihrem Unternehmen gesucht haben, und interessieren sich für weitere Daten dazu, wie Ihre Einträge gefunden werden.

BITTE BEACHTEN: Zum Testen dieser APIs benötigen Sie einen bestehenden Produktions-Account mit einem aktiven Listings-Abonnement.

Erstellung und Abfrage von Berichten

Analytics zu Listings sind in Form von Berichten verfügbar, die synchron oder asynchron erstellt werden können. Letzterer Ansatz wird empfohlen, wenn Sie große Datenmengen abrufen möchten. Er erfordert zwei API-Calls: einen, um von den Servern von Yext einen Bericht erstellen zu lassen, und einen weiteren, um den Bericht abzurufen. Wir werden später ausführlicher über asynchrone Berichte sprechen. Lassen Sie uns zunächst einen einfachen, synchronen Bericht erstellen.

Synchrone Berichte

Um einen Bericht zu erstellen und sofort die entsprechenden Ergebnisse zu erhalten, senden Sie bitte folgende API-Anfrage:

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

Header:
Content-Type: application/json

Text:
{
  "metrics": [
    "POWERLISTINGS_LIVE"
  ],
  "dimensions": [
    "DAYS"
  ],
  "filters": {
    "startDate": "2014-01-01",
    "endDate": "2014-01-05"
  }
}
Dieser Bericht umfasst die Anzahl von Einträgen, die zwischen dem 1. Januar 2014 und dem 5. Januar 2014 pro Tag live waren. Bei einer erfolgreichen Anfrage sollten Sie folgende Antwort erhalten:
{
  "meta": {
    "uuid": "9faae6d8-f6e0-45d2-9307-9d2afbfe75e5",
    "errors": []
  },
  "response": {
    "data": [
      {
        "PowerListings Live": 100,
        "day": "1/01/14"
      },
      {
        "PowerListings Live": 100,
        "day": "1/02/14"
      },
      {
        "PowerListings Live": 100,
        "day": "1/03/14"
      },
      {
        "PowerListings Live": 100,
        "day": "1/04/14"
      },
      {
        "PowerListings Live": 100,
        "day": "1/05/14"
      }
    ]
  }
}

Asynchrone Berichte

Wir haben also einen einfachen Bericht erstellt, bei dem die Ergebnisse sofort anzeigt werden. Lassen Sie uns jetzt versuchen, einen asynchronen Bericht zu erstellen. Verwenden Sie die gleiche Aufforderung wie zuvor, geben Sie aber jetzt den Parameter async in der URL an und setzen Sie ihn auf true:

POST https://api.yext.com/v2/accounts/me/analytics/reports?api_key=API_KEY&v=YYYYMMDD&async=true

Header:
Content-Type: application/json

Text:
{
  "metrics": [
    "POWERLISTINGS_LIVE"
  ],
  "dimensions": [
    "DAYS"
  ],
  "filters": {
    "startDate": "2014-01-01",
    "endDate": "2014-01-05"
  }
}
Diesmal sollte der Antworttext wie in untenstehendem Beispiel aussehen:
{
  "meta": {
    "uuid": "6c524b78-9356-4f06-8966-4e08e84abf8b",
    "errors": []
  },
  "response": {
    "id": "5163607c-1386-4d82-989b-61e7f8340ff8"
  }
}
Wie Sie sehen, enthält das Antwortfeld jetzt nur eine id. Dieser Wert entspricht dem Analytics-Bericht, den Yext unter Berücksichtigung der Kriterien, die Sie in dem API-Call angegeben haben, erstellt.

Mithilfe dieses API-Calls können Sie sich den Status des Berichts anzeigen lassen:

GEThttps://api.yext.com/v2/accounts/me/analytics/standardreports/REPORT_ID?api_key=API_KEY&v=YYYYMMDD

Wenn Sie die id aus der erhaltenen Antwort für obigen Call verwenden, sollten Sie eine Antwort erhalten, die etwa so aussieht:
{
  "meta": {
    "uuid": "558c12d5-fff2-4634-a6ed-5c8ebcaca2a5",
    "errors": [
    ]
  },
  "response": {
    "status": "DONE",
    "url": "https://yext.analytics.s3.amazonaws.com/api/async/current/reports/20161017_101800_5163607c-1386-4d82-989b-61e7f8340ff8_start-date_2014-01-01_end-date_2014-01-05.csv"
  }
}
Über die erhaltene URL kann eine CSV-Datei mit dem gewünschten Bericht heruntergeladen werden. Sollte der Bericht noch nicht vollständig sein, erscheint als StatusPENDING und das Feld URL ist leer. In diesem Fall müssen Sie den API-Call in Abständen wiederholen, bis der Status DONE lautet. Berichte werden üblicherweise innerhalb weniger Sekunden erstellt. Wenn Sie jedoch eine große Datenmenge abfragen, kann die Berichterstellung länger dauern.

Höchstfristen für Berichte

Bevor es mit komplexeren Berichten weitergeht, lassen Sie uns kurz über Höchstfristen für Berichte sprechen. Im Allgemeinen machen die Publisher von Yext tâglich neue Daten verfügbar. Bing liefert allerdings alle zwei Wochen Daten zu seinen Einträgen. Somit kann es sein, dass die für Bing-Einträge verfügbaren Daten nicht mit denen für das restliche Publisher-Netzwerk von Yext übereinstimmen. Über folgende API-Anfrage können Sie sich anzeigen lassen, welche Daten für Bing bzw. für unser restliches Netzwerk verfügbar sind:

GET https://api.yext.com/v2/accounts/me/analytics/maxdates?api_key=API_KEY&v=YYYYMMDD

Antwort:
{
  "meta": {
    "uuid": "ffc8f2bb-0bce-4400-af12-5c34854b72df",
    "errors": [
      
    ]
  },
  "response": {
    "standardMaxDate": "2016-10-04",
    "bingMaxDate": "2016-10-02"
  }
}
Bei einer erfolgreichen Anfrage sollten Sie obenstehende Antwort erhalten. Wie Sie sehen, erscheinen zwei „MaxDate“-Felder: eines für das Standard-Publisher-Netzwerk und eines für Bing. Entsprechend Ihren Bedürfnissen verwenden Sie vielleicht lieber das eine oder das andere Datum zum Filtern Ihrer Daten. Im Durchschnitt liegen diese Daten etwa zwei Wochen vor dem aktuellen Datum.

Erstellung häufig gewünschter Arten von Berichten

Jetzt wissen Sie also, was es mit Höchstfristen für Berichte auf sich hat, und haben bereits einige Berichte erstellt. Lassen Sie uns dieses Wissen jetzt gleich einsetzen und noch ein paar weitere Berichte erstellen. Bitte beachten Sie, dass all diese Beispiele asynchrone Berichte erzeugen und Antworten liefern können, die denen, die Sie erhalten, ähneln, aber nicht genau gleich sind.

Suchen nach Einträgen

Für diesen Bericht fordern wir an, dass die Daten zu SEARCHES und BING_SEARCHES nach Woche afgeschlüsselt werden. Wie die Namen vermuten lassen, sind die von BING_SEARCHES und GOOGLE_SEARCH_QUERIES verwendeten Messgrößen spezifisch für Bing bzw. Google. Den Anforderungstext für die Erstellung dieses Berichtes finden Sie nachfolgend. Bitte beachten Sie, dass das endDate vor dem bingMaxDate liegt. Führen Sie also die Abfrage durch und lassen Sie sich den entsprechenden Bericht anzeigen.
{
  "metrics": [
    "SEARCHES",
    "BING_SEARCHES",
    "GOOGLE_SEARCH_QUERIES"
  ],
  "dimensions": [
    "WEEKS"
  ],
  "filters": {
    "startDate": "2016-08-01",
    "endDate": "2016-10-01"
  }
}

Ansichten von Einträgen nach Standort-IDs

Dieser Bericht zeigt die Seitenaufrufe für Ihre Einträge an. Da Yelp und Google verschiedene Messgrößen für Seitenaufrufe verwenden, werden diese in der unten stehender Anforderung angegeben:
{
  "metrics": [
    "PROFILE_VIEWS",
    "YELP_PAGE_VIEWS",
    "GOOGLE_SEARCH_VIEWS"
  ],
  "dimensions": [
    "DAYS”,
    “LOCATION_IDS”
  ],
  "filters": {
    "startDate": "2016-08-01",
    "endDate": "2016-08-15"
  }
}

Foursquare-Check-ins

Dieser Bericht liefert die täglichen Check-ins für Ihre Foursquare-Einträge unter Berücksichtigung Foursquare-spezifischer Kriterien. Diese Kriterien sind: FOURSQUARE_GENDER (Check-ins von männlichen bzw. weiblichen Nutzern), FOURSQUARE_AGE (Check-ins nach Altersgruppen) und FOURSQUARE_TIME (Check-ins nach Tageszeit). Bitte beachten Sie, dass Sie Foursquare-Check-ins nur nach jeweils einem Foursquare-Kriterium segmentieren können. (Sie können Foursquare-Check-ins z. B. nicht gleichzeitig nach FOURSQUARE_AGE und FOURSQUARE_TIME segmentieren.
{
  "metrics": [
    "FOURSQUARE_DAILY_CHECKINS"
  ],
  "dimensions": [
    "FOURSQUARE_TIME",
    "DAYS"
  ],
  "filters": {
    "startDate": "2016-08-01",
    "endDate": "2016-08-15"
  }
}
Wie Sie an diesen Beispielen sehen, können Sie über die Analytics-API verschiedene Berichte erstellen. Von einem einfachen Bericht darüber, wie viele Einträge täglich gesehen live sind, bis hin zur Anzeige der verschiedenen Seiten-Anzeige-Messgrößen in einem einzigen Bericht – Sie haben zahlreiche Möglichkeiten!

Aktivitätsprotokoll

Neben den Daten, die Yext über das PowerListings®-Netzwerk erhält, können Sie sich auch Analytics zu den Aktionen anzeigen lassen, die auf Ihrem Account von Ihnen oder in Ihrem Namen durchgeführt wurden. Zu diesen Aktionen zählen die Aktualisierung des Namens eines Standortes, die Veröffentlichung eines Social-Media-Posts usw. Aktivitäts-Historie: Mit „POST Endpunkt“ können Sie einen Bericht erstellen, aus dem hervorgeht, welche Änderungen vorgenommen wurden und von wem.

POST https://api.yext.com/v2/accounts/me/analytics/activity?api_key=API_KEY&v=YYYYMMDD

Standardmäßig ergibt diese Abfrage die 50 neuesten Aktionen, die auf Ihrem Account vorgenommen wurden. Sie können bis zu 200 Aktionen auf einmal abfragen. Zudem können Sie Aktionen für einen bestimmten Standort, einer bestimmten Art, von einem bestimmten Nutzer oder innerhalb eines bestimmten Zeitraumes abfragen. Bei einer erfolgreichen Abfrage sollten Sie eine Antwort erhalten, die etwa folgendermaßen aussieht:
{
  "meta": {
    "uuid": "cbf553e3-08e5-48c6-a032-3540722a891f",
    "errors": []
  },
  "response": {
    "activities": [
      {
        "date": {
          "iMillis": 1476284959000,
          "iChronology": {
            "iBase": {
              "iMinDaysInFirstWeek": 4
            }
          }
        },
        "locationId": "Test-Standort1",
        "details": "New Social post on Widgets",
        "content": "Sichern Sie sich tolle Angebote!",
        "type": "SOCIAL_POST",
        "actor": ""
      },
      {
        "date": {
          "iMillis": 1476284872000,
          "iChronology": {
            "iBase": {
              "iMinDaysInFirstWeek": 4
            }
          }
        },
        "locationId": "Test-Standort1",
        "details": "New Social post on Widgets",
        "content": "Kommen Sie noch heute vorbei",
        "type": "SOCIAL_POST",
        "actor": ""
      },
      {
        "date": {
          "iMillis": 1475703866000,
          "iChronology": {
            "iBase": {
              "iMinDaysInFirstWeek": 4
            }
          }
        },
        "locationId": "1231611",
        "details": "Staff Bios field updated",
        "content": "",
        "type": "PROFILE_UPDATE",
        "actor": "Employee"
      }
    ]
  }
}
Einige der erhaltenen Aktionen umfassen Profilaktualisierungen und die Erstellung neuer Posts auf Social Media. Es kann auch sein, dass Ihnen Aktionen angezeigt werden, die von einem API-Nutzer oder einem bestimmten Nutzer über die Yext-UI vorgenommen wurden. Diese Daten sollen Ihnen helfen, ein besseres Verständnis dafür zu bekommen, welche Änderungen an Ihren Daten vorgenommen wurden und von wem.