Working with Analytics
You’ve managed to create a Location and send its data to Yext’s publisher network via our APIs. Now you may be wondering how many people have viewed its listings, how many people have searched for your business on our network, and other data about how your listings are being found.

NOTE: To test these APIs, you will need to use an existing production account with an active Listings subscription.

Creating And Retrieving a Report

Listings analytics are provided in reports, which can be provided either synchronously or asynchronously. The latter approach is recommended whenever you want to fetch a large amount of data; it requires two API calls — one to tell Yext’s servers to create a report and a second to retrieve the report. We’ll talk about the asynchronous reports a bit later, but for now let’s create a simple, synchronous report.

Synchronous reports

To create a report and get the results immediately, send the following API request:

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

Header:
Content-Type: application/json

Body:
{
  "metrics": [
    "POWERLISTINGS_LIVE"
  ],
  "dimensions": [
    "DAYS"
  ],
  "filters": {
    "startDate": "2014-01-01",
    "endDate": "2014-01-05"
  }
}
This report returns the number of listings that were live each day from January 1, 2014 through January 5, 2014. If the request is successful, you should receive this response:
{
  "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"
      }
    ]
  }
}

Asynchronous Reports

We created a simple report that return results immediately, so now let’s try creating an asynchronous report. Use the same call as before, but this time include the async parameter in the URL and set it to true:

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

Header:
Content-Type: application/json

Body:
{
  "metrics": [
    "POWERLISTINGS_LIVE"
  ],
  "dimensions": [
    "DAYS"
  ],
  "filters": {
    "startDate": "2014-01-01",
    "endDate": "2014-01-05"
  }
}
This time, the response body should look like the example below:
{
  "meta": {
    "uuid": "6c524b78-9356-4f06-8966-4e08e84abf8b",
    "errors": []
  },
  "response": {
    "id": "5163607c-1386-4d82-989b-61e7f8340ff8"
  }
}
Notice how the response field now only contains an id . This value corresponds to the analytics report Yext is generating using the criteria you specified in the API call.

You can see the status of the report by making this API call:

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

If you use the id from the returned response to make the call above, you should get a response like the one below:
{
  "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"
  }
}
The URL returned will download a CSV file with the requested report. In cases where the report is not yet fully generated, the status will be PENDING and the url field will be blank. In these cases, you will need to periodically make the API call until the status is DONE. Usually reports are generated within a few seconds, but if you request a large amount of data, the report generation may take longer.

Maximum Report Dates

Before we talk about more complex reports, let’s talk about maximum report dates. In general, Yext’s publishers provide data on a daily basis; however, Bing provides data on their listings every two weeks. As a result, the available data for Bing’s listings may not align with the rest of Yext’s publisher network. To see up to what date we have data for either Bing or the rest of our network, make the following API request:

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

Response:
{
  "meta": {
    "uuid": "ffc8f2bb-0bce-4400-af12-5c34854b72df",
    "errors": [
      
    ]
  },
  "response": {
    "standardMaxDate": "2016-10-04",
    "bingMaxDate": "2016-10-02"
  }
}
If the call is successful, you should see the response body above. Note there are two “MaxDate” fields returned: one for the standard publisher network and one for Bing. Depending on your needs, you may prefer to use one date over the other when filtering your data. On average, these dates are usually about two weeks before today’s date.

Generating Common Reports

Now that you’ve learned about maximum report dates and have generated a few reports, let’s try to generate a few more using this knowledge. Note that all the examples below will generate asynchronous reports and may return responses that are similar to, yet different from responses you receive.

Searches for Listings

In this report, we will request the SEARCHES and BING_SEARCHES data to be broken down by week. As the name suggests, the metrics BING_SEARCHES and GOOGLE_SEARCH_QUERIES are unique to Bing and Google, respectively. The request body to generate this report is given below. Note how the endDate is before the bingMaxDate . Go ahead and make the call and see the generated report.
{
  "metrics": [
    "SEARCHES",
    "BING_SEARCHES",
    "GOOGLE_SEARCH_QUERIES"
  ],
  "dimensions": [
    "WEEKS"
  ],
  "filters": {
    "startDate": "2016-08-01",
    "endDate": "2016-10-01"
  }
}

Listings views by Location IDs

This report generates the page views for your listings. Since Yelp and Gogole have different metrics for page views, those are noted in the request below:
{
  "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

This report fetches the daily check-ins for your Foursquare listings using dimensions specific to Foursquare. These dimensions are FOURSQUARE_GENDER (check-ins by male vs. female), FOURSQUARE_AGE (check-ins broken by age group) and FOURSQUARE_TIME (check-ins by time of day). Note you can only segment Foursquare check-ins by one Foursquare dimension at a time (e.g., you cannot segment Foursquare check-ins by both FOURSQUARE_AGE and FOURSQUARE_TIME).
{
  "metrics": [
    "FOURSQUARE_DAILY_CHECKINS"
  ],
  "dimensions": [
    "FOURSQUARE_TIME",
    "DAYS"
  ],
  "filters": {
    "startDate": "2016-08-01",
    "endDate": "2016-08-15"
  }
}
As you can tell from these examples, there are number of reports you can generate using the Analytics API. From a simple report about how many of your listings are live on a daily basis to viewing the various page-view metrics in a single report, the possibilities are tremendous!

Activity Log

Aside from the data Yext receives from the PowerListings® Network, you can also get analytics on the actions that were taken in your account by you or on your behalf. Some actions include updating the name of a Location, publishing a social post, and so on. The Activity Log: POST endpoint allows you to generate a report to see what changes were made and by whom.

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

By default, this request will return the 50 most recent actions taken in your account. You can request up to 200 actions at a time. In addition, you can request actions for a specific Location, of a specific type, made by a specific user, or within a certain date range. If the request above was successful, you should receive a response like the one below:
{
  "meta": {
    "uuid": "cbf553e3-08e5-48c6-a032-3540722a891f",
    "errors": []
  },
  "response": {
    "activities": [
      {
        "date": {
          "iMillis": 1476284959000,
          "iChronology": {
            "iBase": {
              "iMinDaysInFirstWeek": 4
            }
          }
        },
        "locationId": "TestLocation1",
        "details": "New Social post on Widgets",
        "content": "Come in for some great deals!",
        "type": "SOCIAL_POST",
        "actor": ""
      },
      {
        "date": {
          "iMillis": 1476284872000,
          "iChronology": {
            "iBase": {
              "iMinDaysInFirstWeek": 4
            }
          }
        },
        "locationId": "TestLocation1",
        "details": "New Social post on Widgets",
        "content": "Call Today",
        "type": "SOCIAL_POST",
        "actor": ""
      },
      {
        "date": {
          "iMillis": 1475703866000,
          "iChronology": {
            "iBase": {
              "iMinDaysInFirstWeek": 4
            }
          }
        },
        "locationId": "1231611",
        "details": "Staff Bios field updated",
        "content": "",
        "type": "PROFILE_UPDATE",
        "actor": "Employee"
      }
    ]
  }
}
Some of the actions returned include a profile update and creating new social posts. You may also see actions taken by an API user or by a specific user through the Yext UI. All of these records are to help you better understand the changes made to your data and by what party.