Why we built them and how you can integrate them into your team’s client reporting processes.
It should come as no surprise that our customers and Partners are the driving force behind product development. How you interact with our product and the feedback you provide us with, give us invaluable insights that we use to give you the content and features you need to be successful.
We understand there is value in being transparent. Which is why we want you to live vicariously through our content builders as they create pre-built HubSpot metrics that you can then leverage to get value, fast.
We hope to provide you with tips on how to approach building HubSpot content for your clients. Through this process, we hope to initiate a 2-way dialogue with you - sharing your ideas and successes will set us on a path to developing features in app that will benefit you and others.
The key questions we ask ourselves when we set out to pre-build content include:
Let’s start with the HubSpot Sessions by Channel metric and go from there. We’ll end the article sharing the definition of the specific pre-build metrics we have recently created for HubSpot.
Is HubSpot Sessions by Channel of interest to customers/partners?
We look towards our customers to help prioritize investments, and if many care about something or are asking about it, we increase the priority. We have hundreds of customers who have built thousands of HubSpot data sources (granted, these have been primarily for building Klips to-date, but it does emphasize the interest in Hubspot as a source of data for monitoring business performance).
Sessions is a common metric used by a large percentage of our customers. After conducting a survey of our marketing agency partners, we found that sessions, leads and conversions are the most common metrics they are monitoring in Klipfolio. This finding alone sparked our initiative to build a reusable asset that many customers and partners could leverage.
As we consider investing to create a new metric, we get the following attributes of the metric:
For more information on Sessions from HubSpot visit:
Can I get the data from HubSpot? And will it be useful?
This is one of the bigger challenges faced when pre-building a metric -- does the data exist in the service we are looking at AND does it get exposed via the API. We have found cases where a particular metric or number may exist in the application UI, however does not get exposed through the API for us to leverage. For example, HubSpot has not published an API for prospects or to get email click through rates.
Most often, the requests come in because users have seen the metric somewhere in the application.
For HubSpot, we used the HubSpot API documentation to investigate.
Klipfolio already invested in ensuring a connection to HubSpot is possible, created the mechanism to request an OAuth Token for authentication and ensured we can send a query and receive a response to get data.
The HubSpot analytics API enables leveraging the Sources report to quickly get to Sessions data.
Are there any surprises in the HubSpot API?
The HubSpot API is actually made up of a number of APIs with differing attributes. Most of them are transactional in nature and can result in a lot of detail being returned - sometimes too much detail if you want a lot of history. With the introduction of PowerMetrics, Klipfolio will now store data for a metric over time. This ends up enabling a smaller query which incrementally grows the history of a metric over time. The APIs also differ in the structure of the results, number of records returned per page, and even rate limits.
OAuth is the most common authentication method.
HubSpot in particular uses OAuth and has a number of endpoints that behave very differently (when looking at the HubSpot API documentation, it looks like there could be as many as 40+ endpoints, though some are deprecated). This is why we are planning to create a separate connection for the HubSpot Analytics API to help simplify things further and reflect the variations.
Here are a few key ways some of the HubSpot endpoints differ:
Some endpoints will use a ‘limit’ parameter to say how many items to return on one page (e.g. Deals API) , others might use ‘count’ to do the same thing (e.g. Contacts Api). Some endpoints will return the id of the last item on the response/page as offset value which can be used in a follow-up request (Deals API) to get additional pages, while other responses will return simply the page number where offset = 0 is the first page (Pages API)
Let’s focus on the HubSpot Analytics API for the Sessions by Channel metric.
Unlike some other APIs where you can be really granular in terms of which measures and dimensions you want to include in the results (e.g. Google Analytics), the HubSpot Analytics API returns set response with a number of measures. So far, we have found that for any set of measures being returned for an endpoint, we can get a data field and one dimension for context. Klipfolio’s metrics thrive on dimensions. More dimensions means much more flexibility on what a user can do to understand the context around a metric. We should also point out that more measures and more dimensions often results in a lot more data coming back from the service. To offset that, some other services may start sampling data (possibly unbeknownst to users - so watch for that.) HubSpot is not sampling data (as far as we can determine).
To accommodate the responses only having one dimension (in addition to date), we have been adding multiple metrics in Klipfolio for key dimensions. For example:
Unfortunately, this also means there is no mechanism to deconstruct the data in such a way that we could then combine the dimensions into a single.
Here is a subset of the data returned from the HubSpot API for Sessions by Channel:
How did we enhance the data in the model to prepare it for the metric?
The big things we do in the model is prepare the data for the metric and ensure it is structured to be used by metrics.
Align the data - if your data is coming back as tree-structured (JSON or XML), we use XPath and functions to enhance align the data. Common situations include filling spaces for scarce data (not all nodes in the trees have all attributes), duplicating a node name across multiple entries, etc..
Enhance the data -you can add calculations to your model, filter data out of the results, and use the merge functionality in modelled data sources to replace IDs with more intuitive names - essentially doing a lookup. Merging data sources may also help with adding more dimensions for your metric.
What would I do differently if building a Klip vs. building a Metric?
Most data sources that have a date, a measure and at least one dimension could be well suited for metrics. Some things to consider:
This document focused on building a query or data source optimized to support a metric.
Originally published May 28, 2019, updated Nov, 04 2020