Analytics
Fetch Google, Bing, and Facebook profile analytics with the listingsapi-js SDK.
The analytics methods retrieve platform-level insights, such as search
impressions, clicks, direction requests, and phone calls, from Google
Business Profile, Bing Places, and Facebook Pages. All analytics methods
live directly on the ListingsAPI client instance and are scoped to a
location ID. Numeric location IDs are encoded automatically, so 16808 and
'TG9jYXRpb246MTY4MDg=' are interchangeable.
All three methods share the same signature: a location ID plus an optional
{ fromDate, toDate } range. Both dates are optional, individually or
together; omit them to use the platform's default reporting window.
Every metric is a time series
There are no scalar totals in these payloads. Each metric is an array of
{ startTime, value } points, one per day (per week for Bing), and a metric
you have no data for is null rather than 0 or []. So sum the series
yourself, and keep "no data" distinct from "zero":
type Point = { startTime: string; value: number | null }; // null when the metric is absent, so an empty profile never reads as 0.function sumSeries(series: Point[] | null | undefined): number | null {if (!Array.isArray(series)) return null;return series.reduce((acc, p) => acc + (p.value ?? 0), 0);} function show(label: string, series: Point[] | null | undefined) {const total = sumSeries(series);console.log(label, total === null ? 'unavailable' : total);}fetchGoogleAnalytics
Fetch Google Business Profile insights for a location.
const google = await client.fetchGoogleAnalytics(16808, {fromDate: '2024-01-01',toDate: '2024-12-31',}); show('Impressions (total)', google.total);show('Search impressions', google.search);show('Maps impressions', google.maps);show('Website clicks', google.websiteAction);Options
The payload is the googleInsights object, and every key on it is a
{ startTime, value }[] series: total, search, maps, websiteAction,
directionsAction, phoneAction, businessBookings, businessFoodOrders,
and businessFoodMenuClicks. total is profile impressions, search plus
maps; it does not include the action metrics. Any series Google has no data
for comes back null. See
Get Google analytics for a location for
the full field reference.
fetchBingAnalytics
Fetch Bing Places insights for a location.
const bing = await client.fetchBingAnalytics(16808, {fromDate: '2024-01-01',toDate: '2024-12-31',}); show('Bing views', bing.views);Bing reports a single metric, views, bucketed weekly rather than daily.
Options
fetchFacebookAnalytics
Fetch Facebook page insights for a location.
const facebook = await client.fetchFacebookAnalytics(16808, {fromDate: '2024-01-01',toDate: '2024-12-31',}); show('Page views', facebook.views);show('CTA clicks', facebook.ctaAction);The Facebook payload carries views, ctaAction, websiteAction,
directionsAction, and phoneAction. There is no pageLikes.
Options
Multi-platform report
Fetch all three platforms in parallel with Promise.all:
import { ListingsAPI } from 'listingsapi-js'; const client = new ListingsAPI(); // reads LISTINGSAPI_KEY from envconst LOCATION_ID = 16808;const range = { fromDate: '2024-01-01', toDate: '2024-12-31' }; const [google, bing, facebook] = await Promise.all([client.fetchGoogleAnalytics(LOCATION_ID, range),client.fetchBingAnalytics(LOCATION_ID, range),client.fetchFacebookAnalytics(LOCATION_ID, range),]); show('Google impressions:', google.total);show('Bing views:', bing.views);show('Facebook views:', facebook.views);If a profile is not connected for a given platform, the method resolves with
an empty object rather than rejecting, and an individual series comes back
null. Report that as "unavailable" rather than coercing it to 0 with
??, or a disconnected profile reads as a real zero in your dashboard.
Request failures still throw the SDK's typed errors.