Analytics Catalog Use Cases | Yext Hitchhikers Platform

Below are a few use cases for when the Analytics API Catalog will come in handy when interacting with Yext.

Find All Queryable Metrics Programmatically

With the Analytics API Catalog, you now have your source of truth for which metrics are available to you via the API with its corresponding ID.

Querying Only Complete Data for Metric

To make informed decisions with Yext Analytics you’ll want to make sure the data you’re looking at is “complete” and is unlikely to change going forward.

With that in mind, your best approach is to query the Analytics API Catalog first to return each of the metrics, and their corresponding Completed Date, and use that date to query the API for Analytics as of that date.

For example, imagine you’d like to return the most complete data possible for the GOOGLE_SEARCH_VIEWS metric.

To do that you’d:

Query the Analytics Data Catalog

Issue a GET Request against the Catalog endpoint with your corresponding API Key and a V parameter greater than or equal to 20210415

Catalog Response:

{
    "meta": {
        "uuid": "88968fc0-ef3d-44c8-8a50-a3dadd059334",
        "errors": []
    },
    "response": {
        "metrics": [
            {
                "id": "BING_SEARCHES",
                "completedDate": "2021-03-14"
            },
            {
                "id": "FACEBOOK_POST_IMPRESSIONS",
                "completedDate": "2021-03-22"
            },
            {
                "id": "GOOGLE_SEARCH_VIEWS",
                "completedDate": "2021-03-24"
            }
        ]
    }
}

From this response you can see that complete data for the GOOGLE_SEARCH_VIEWS metric is available up to and including 2021-03-24.

Query Analytics API

Once you’ve retrieved the Completed Date for the metric you’re interested in query, e.g., GOOGLE_SEARCH_VIEWS, you can now use that date in your query to limit it to only complete data in the Yext Analytics API.

Request Body

{
        "metrics":
            [
            "GOOGLE_SEARCH_VIEWS"
                    ],
        "dimensions": [
            "DAYS"
                ],
        "filters": {
            "startDate": "2021-03-20",
            "endDate": "2021-03-25"
                }
        }

Request Response

{
    "meta": {
        "uuid": "cb1d327e-041d-4eb1-b467-6d6c0f1bd39c",
        "errors": []
    },
    "response": {
        "data": [
            {
                "day": "2021-03-20",
                "Google Search Views": 46492
            },
            {
                "day": "2021-03-21",
                "Google Search Views": 46362
            },
            {
                "day": "2021-03-22",
                "Google Search Views": 138815
            },
            {
                "day": "2021-03-23",
                "Google Search Views": 129726
            },
            {
                "day": "2021-03-24",
                "Google Search Views": 123751
            }
        ]
    }
}

Query Incomplete Data

While most of the time you’ll only want to query “complete” data to ensure you’re making the best decisions possible there may be cases where you’d like to query more recent data even if it is not complete yet e.g. if you’re a Partner who’d like to display that data in your platform immediately.

To do that you’ll want to:

1. Query the Complete Data: Using the method described above, query all complete data available for a given metric.
2. Save the Completed Date: For each metric you previously queried, save the completed date to use the next time you request data from the Analytics API.
3. Query the Incomplete Data: Using the Completed Date saved for each metric in step two, query the API for all incomplete data, e.g., dates > completed date, to retrieve any data that may have changed.

This will ensure you’re only requesting new data that may have changed since the last time you extracted data from the Analytics API as date before the completed date should not change.

For example, using the same GOOGLE_SEARCH_VIEWS metric above, you’ll want to query data after 3/24/21 as this was the Completed Date as of your last run:

V parameter must be greater than or equal to 20210415

Request Body

{
        "metrics":
            [
            "GOOGLE_SEARCH_VIEWS"
                    ],
        "dimensions": [
            "DAYS"
                ],
        "filters": {
            "startDate": "2021-03-25",
            "endDate": "2021-03-29"
                }
        }

Request Response

{
    "meta": {
        "uuid": "2a59b848-ac87-4748-a212-5bd5099d8a11",
        "errors": []
    },
    "response": {
        "data": [
            {
                "day": "2021-03-24",
                "Google Search Views": 123751
            },
            {
                "day": "2021-03-25",
                "Google Search Views": 100324
            },
            {
                "day": "2021-03-26",
                "Google Search Views": 98203
            },
            {
                "day": "2021-03-27",
                "Google Search Views": 120319
            },
        ]
    }
}

This will return you all of the data available within the Yext Analytics API after the Completed Date at the given moment.

If no incomplete data is available for a given time period, the API will return no data for these days e.g., 3/28/21 and 3/29/21 in the sample request body above.