Introduction
Our mission is to enable your growth and satisfaction through flexible access to digital marketing reporting data.
We have 3 major approaches for providing data: APIs, Webhooks and Integration apps.
API
Interface to the data – through a request & response interchange between applications
APIs that serve up metrics for your Search, Display, and Social Campaigns. There are also APIs that serve up campaign level metrics independent of the product.
Webhooks
Event driven interface to the data – automated exchange based on specific event or rules occurring
Webhooks for contact creation on the LocaliQ platform
Webhooks for interactions occurring on your campaign; call, chat, web & email events.
Integrations
API and/or Web hooks with a specific purpose
CRM integrations (Contacts and Leads)
FranConnect Integration
This site describes the resources that make up the LocaliQ reporting REST API offerings. For questions or general information, please contact us at:
LocaliQ API Support: Contact your LocaliQ account representative.
Terms And Conditions
Use of any LocaliQ Application Program Interface(s) (collectively, the “API Service”) is subject to the LocaliQ Online Marketing Services Terms and Conditions as set forth at www.localiq.com/tc (the “Marketing Services Terms”), including, without limitation, the Client Center Product Terms, and any other applicable agreement between you and LocaliQ. LocaliQ provides the API Service as an extension of the Client Center software and reserves the exclusive right to limit or revoke access to the API Service at any time and for any reason.
Your download, transfer and/or removal of any information through the API Service is solely at your own risk. LocaliQ is not responsible for the safety, security or legality of the transmission of your data or of your or any third-party’s platform or system to which you transmit the data. Due to technical processing and transmission requirements of the API Service, your information is transferred unencrypted and may involve (a) transmissions over various networks and (b) changes to conform and adapt to technical requirements of connecting to various networks, systems or devices.
THE API SERVICE IS PROVIDED ON AN "AS IS" AND "AS AVAILABLE" BASIS, WITHOUT ANY WARRANTY OF ANY KIND AND WITHOUT ANY GUARANTEE OF CONTINUOUS OR UNINTERRUPTED AVAILABILITY. IN ADDITION TO THE DISCLAIMERS SET FORTH IN THE MARKETING SERVICES TERMS, LOCALIQ (I) MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE ACCURACY OR COMPLETENESS OF ANY INFORMATION PROVIDED TO YOU BY OR ON BEHALF OF LOCALIQ (INCLUDING ANY REPORTING, ANALYTICS AND SIMILAR INFORMATION) OR ANY CONTENT AVAILABLE ON OR THROUGH THE API SERVICE; AND (II) IS NOT RESPONSIBLE FOR ANY ERRORS, DEFECTS OR DOWNTIME CAUSED BY YOUR USE OF THE API SERVICE.
Getting Started
We have a two-step access process; authentication and authorization.
The authentication process registers your application to a business user email.
The authorization process determines the advertising data the business user is allowed to access.
Note: Business user’s access to advertiser’s data (GMAIDs) is maintained through Campaign Central/Corp Portal.
Step 1: Request API Access
The first step is to register your application with LocaliQ. Please contact your account manager or DMC to request API access.
You will get a response within 1 business day. The response email will contain a Client Id and a Client Secret token.
The Client Id token is a public identifier for your application that will differentiate it amongst other LocaliQ API integrations.
The client secret is a secret known only to the application and the authorization server.
Step 2: Authorization/Authentication
The second step involves receiving an Authorization token, which is then used to request an Access and Refresh token. There are two ways to receive an Authorization token: User login method and Direct access method.
Get Auth Token
User Login Method
Through a browser initiate the authorization with your Client Id and Client Secret tokens [Step 1] and your REDIRECT_URI (the redirect URI is where all API related responses will be sent)
https://api.localiqservices.com/oauth/authorize?client_id=[CLIENT_ID]&response_type=code&redirect_uri=[REDIRECT_URI]
Please enter your business user credentials.
The user (login email) being used for API authentication must be a business user in the LocaliQ platform and have access to the GMAID that will be used in the API
Upon successful authentication, you will be redirected to the REDIRECT_URI along with an Authorization token. This token expires in 10 minutes.
Get Access and Refresh Tokens
Please use the Authorization token to request an Access and Refresh token.
require 'uri'
require 'net/http'
url = URI("https://api.localiqservices.com/oauth/token")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE
request = Net::HTTP::Post.new(url)
request["content-type"] = 'application/json'
request.body = "{\n\t\"client_id\": \"CLIENT_ID\",\n\t\"client_secret\": \"CLIENT_SECRET\",\n\t\"code\": \"AUTHORIZATION_TOKEN\",\n\t\"grant_type\": \"authorization_code\",\n\t\"redirect_uri\": \"REDIRECT_URI\"\n}"
response = http.request(request)
puts response.read_body
OkHttpClient client = new OkHttpClient();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n\t\"client_id\": \"CLIENT_ID\",\n\t\"client_secret\": \"CLIENT_SECRET\",\n\t\"code\": \"AUTHORIZATION_TOKEN\",\n\t\"grant_type\": \"authorization_code\",\n\t\"redirect_uri\": \"REDIRECT_URI\"\n}");
Request request = new Request.Builder()
.url("https://api.localiqservices.com/oauth/token")
.post(body)
.addHeader("content-type", "application/json")
.build();
Response response = client.newCall(request).execute();
curl -X POST \
https://api.localiqservices.com/oauth/token \
-H 'content-type: application/json' \
-d '{
"client_id": "CLIENT_ID",
"client_secret": "CLIENT_SECRET",
"code": "AUTHORIZATION_TOKEN",
"grant_type": "authorization_code",
"redirect_uri": "REDIRECT_URI"
}'
The above command returns JSON structured like this:
{
"access_token": "8821d2a47a88d1cbaced1043aee73ccc4608d7cacb068c0eb09e468e91cdb49b",
"token_type": "bearer",
"expires_in": 7200,
"refresh_token": "5d59deea16599eb316a63989a9974568da4f5570e7ef9969c693f0b1ce1052cb",
"created_at": 1495549720
}
Direct Access Method
Another way to get the Authorization, Access and Refresh tokens today is to use the direct access approach. OAuth 2 provides a "password" grant type which can be used to exchange your business user credentials for an Access token directly. This method is easier to use for straight API integrations where user interaction isn't desired or possible.
Replace the CLIENT_ID, CLIENT_SECRET, USERNAME and PASSWORD with the correct values for your account.
require 'uri'
require 'net/http'
url = URI("https://api.localiqservices.com/oauth/token")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n\t\"client_id\": \"CLIENT_ID\",\n\t\"client_secret\": \"CLIENT_SECRET\",\n\t\"grant_type\":\"password\",\n\t\"username\":\"USERNAME\",\n\t\"password\":\"PASSWORD\"\n}"
response = http.request(request)
puts response.read_body
OkHttpClient client = new OkHttpClient();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n\t\"client_id\": \"CLIENT_ID\",\n\t\"client_secret\": \"CLIENT_SECRET\",\n\t\"grant_type\":\"password\",\n\t\"username\":\"USERNAME\",\n\t\"password\":\"PASSWORD\"\n}");
Request request = new Request.Builder()
.url("https://api.localiqservices.com/oauth/token")
.post(body)
.addHeader("Content-Type", "application/json")
.build();
Response response = client.newCall(request).execute();
curl --request POST \
--url https://api.localiqservices.com/oauth/token \
--header 'Content-Type: application/json' \
--data '{
"client_id": "CLIENT_ID",
"client_secret": "CLIENT_SECRET",
"grant_type":"password",
"username":"USERNAME",
"password":"PASSWORD"
}'
The above command returns JSON structured like this:
{
"access_token": "8821d2a47a88d1cbaced1043aee73ccc4608d7cacb068c0eb09e468e91cdb49b",
"token_type": "bearer",
"expires_in": 7200,
"refresh_token": "5d59deea16599eb316a63989a9974568da4f5570e7ef9969c693f0b1ce1052cb",
"created_at": 1495549720
}
Request New Access Token
The Access token should be passed in the authorization header for all API requests. This Access token expires every 2 hours. If the token has expired, all API calls will receive a 401 HTTP status code response.
You can request a new Access token by using the Refresh token. It is very important that you save the Refresh token for this purpose. If your Refresh token is lost, you would have to authenticate and authorize again [Step 1 and Step 2] to obtain a new Access token and Refresh token.
require 'uri'
require 'net/http'
url = URI("https://api.localiqservices.com/oauth/token")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE
request = Net::HTTP::Post.new(url)
request["content-type"] = 'application/json'
request.body = "{\n\t\"client_id\": \"CLIENT_ID\",\n\t\"client_secret\": \"CLIENT_SECRET\",\n\t\"grant_type\": \"refresh_token\",\n\t\"refresh_token\": \"REFRESH_TOKEN\"\n}"
response = http.request(request)
puts response.read_body
OkHttpClient client = new OkHttpClient();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n\t\"client_id\": \"CLIENT_ID\",\n\t\"client_secret\": \"CLIENT_SECRET\",\n\t\"grant_type\": \"refresh_token\",\n\t\"refresh_token\": \"REFRESH_TOKEN\"\n}");
Request request = new Request.Builder()
.url("https://api.localiqservices.com/oauth/token")
.post(body)
.addHeader("content-type", "application/json")
.build();
Response response = client.newCall(request).execute();
curl --request POST \
--url https://api.localiqservices.com/oauth/token \
--header 'content-type: application/json' \
--data '{
"client_id": "CLIENT_ID",
"client_secret": "CLIENT_SECRET",
"grant_type": "refresh_token",
"refresh_token": "REFRESH_TOKEN"
}'
The above command returns JSON structured like this:
{
"access_token": "62b28b310f73caa88d6968c380ccb85434f4f6379162e01d1bade4b62a62762c",
"token_type": "bearer",
"expires_in": 7200,
"refresh_token": "f2b8a81ca929a4df4d40fe8bb36a379761f91242ac3b26957e3e0a6696235233",
"created_at": 1504822139
}
Security Considerations
Token Security
Refresh tokens are long-lived.
This means when you must store it securely to keep it from being used by potential attacker. For this reason, it is not safe to store them in the browser. If a Refresh token is leaked, it may be used to obtain new Access tokens (and access protected resources) until it is blacklisted.
Access tokens must also be kept secret, but due to its shorter life, security considerations are less critical.
The email address used to obtain the OAuth Access token must be associated with the GMAID of the requested advertiser. If it is not, the API will return an HTTP response with status code 403 and the following body:
{ "name": "not_authorized", "message": "You are not permitted to perform this action." }
Business user credentials
The user (login email) being used for API authentication must be a business user in the LocaliQ platform and have access to the GMAID that will be used in the API. Business User credentials are provided to you by your account team during account creation. These credentials allow you to access the account data through the APIs as well as the Client Center. If you need to check if you have a Business User created or need to reset your password, you can navigate to ReachSecurePay (https://reachsecurepay.com/client/index.php) and enter your email address. If you encounter the error message “Email Address is invalid” or “Email Address not found”, please contact your account management team. If you progress to the login screen, you can select “Create a new password” which will either send you a password reset email or allow you to set your password manually (this will only occur if your password has never been set).
Access to HIPAA data
The business user must have “Agency Customer” role to use the lead APIs. If the API response has PII and the advertiser falls under the HIPAA category, the API will check for this role in order to provide PII information in the response. Please reach your account team to check and/or edit privileges on your business user. Please follow the needed due diligence when adding HIPAA privileges to your business user account since the implications of it are far beyond API access to data. This control applies to APIs that provide data that are classified as HIPAA and protected by law.
API Rate Limits
LocaliQ enforces API rate limits for its REST APIs. Rate limit configuration consists of a per second request limit. Limits are set to 20 requests/second.
If you exceed the rate limit allowance, your request will be rejected. An HTTP 429 (Too Many Requests) response will be returned. Clients must back off until the end of the current rate limit window before making any more requests.
Example response body for throttled request:
{ "message": "Too Many Requests" }
We reserve the right to alter rate limits and other functionality to prevent abuse, spam, denial-of-service attacks, or other security issues. Where possible, we'll return a descriptive error message, but the nature of this type of rate limiting often prevents us from providing more information.
Troubleshooting Errors
400 - Bad Request
Invalid Grant
Example Response
{ "error": "invalid_grant", "error_description": "The provided authorization credentials are invalid. Refer to documentation at https://doc.api.localiq.com/#error-codes for further information." }
Invalid grant error messages occurs when either:
A request is made for an access token with invalid credentials (username or password)
When a request is made to refresh an access token with an expired refresh token, one that has already been used to obtain an access token so it is no longer valid.
To resolve this check your username and password for accuracy, then follow steps at Requesting Access and Refresh Tokens to request a new refresh token.
401 - Unauthorized
Example Response
{ "message": "Unauthorized" }
Unauthorized messages can occur when a request for a report endpoint is made using an expired token.
To resolve this, follow steps at Requesting Access and Refresh Tokens
403 - Forbidden
Example Response
{ "name": "not_authorized", "message": "You are not permitted to perform this action." }
HIPAA Permissions
The business user must be set up to allow access to HIPAA information to access HIPAA data through the API. You can reach your account team to check and/or edit privileges on your business user. Please follow the needed due diligence when adding HIPAA privileges to your business user account since the implications of it are far beyond API access to data.
This control applies to APIs that provide data that are classified as HIPAA and protected by law.
The business user must have "Agency Customer" role to use the lead APIs. If the API response has PII and the advertiser falls under the HIPAA category, the API will check for this role in order to provide PII information in the response.
Release Notes
2023
May
| API(s) Updated | Description |
|---|---|
| N/A | Internal API updates |
| Contact Interactions/Leads | Added target_number |
April
| API(s) Updated | Description |
|---|---|
| N/A | Internal API updates |
| N/A | Added shopping as a recognized campaign type |
| N/A | Updated support and onboarding documentation |
| SocialAds Campaign Metrics | Added purchase conversion metrics for shopping campaigns |
March
| API(s) Updated | Description |
|---|---|
| Search Activity | Chat metrics attributed to the campaigns were not updating. |
| Top Referrers | Added campaign name to source objects |
| Marketing Activity | Added bookings count to Marketing API |
| N/A | Internal API updates |
February
| API(s) Updated | Description |
|---|---|
| Marketing Activity | Migrated microservice cloud provider with no changes other than greatly improved performance. Moved location in documentation. |
| Chat Summary | Migrated microservice cloud provider with no changes other than greatly improved performance. |
| Top Referrer | Migrated microservice cloud provider which necesitated a slight change in the URL path (noted in the documentation). The old URL path is deprecated and will be removed on June 1, 2023. The response body remains unchanged |
| Discovery | This API was previously denoted as deprecated. It remains deprecated, and will be removed on June 1, 2023. The marketing activity API has the same information in an easier to understand format |
| Lead Events (LEFS) | This API was previously denoted as deprecated. It remains deprecated, and will be removed on June 1, 2023. The contact interactions API has more information and an easier to understand format |
| N/A | Refreshed branding of this site |
2024
January
| API(s) Updated | Description |
|---|---|
| Marketing Activity | Added support for SMS channel |
| Contact Interactions | Added support for SMS channel |
| XMO Metrics | Added support for video channel |
| XMO Channel Metrics | Added support for video channel |
2021
July
| API(s) Updated | Description |
|---|---|
| All APIs | General Performance Updates; no impact to the response or usage of the API |
June
| API(s) Updated | Description |
|---|---|
| Social Ads | API update to report frequency only for daily intervals |
| All APIs | General Performance Updates; no impact to the response or usage of the API |
May
| API(s) Updated | Description |
|---|---|
| Campaign Overview | API update to include just qualified web events in lead totals |
| Unified Display | Update to limit the response to include metrics only from display publisdhers (SimpliFi, Gannet Ad Manager & Media Math) |
| Search Metrics | Bug fix related to spend when Include_cycles param is 'False" |
| XMO Metrics | New API for campaign performance metrics for the Cross Media Optimization (XMO) campaigns |
| XMO Channel Metrics | New API for campaign performance metrics by channel (search, social etc.) for the Cross Media Optimization (XMO) campaigns |
| LocaliQ App on Zapier | Upgrade. No change to functionality |
| All APIs | General Performance Updates; no impact to the response or usuage of the API |
April
| API(s) Updated | Description |
|---|---|
| Search Metrics | API update to include just qualified web events in lead totals |
| All APIs | General Performance Updates; no impact to the response or usuage of the API |
March
| API(s) Updated | Description |
|---|---|
| Search Metrics | API update to support a new key; qualified web events |
| Social Ads | API updated to support additional age with gender breakdowns |
| All APIs | General Performance Updates; no impact to the response or usuage of the API |
February
| API(s) Updated | Description |
|---|---|
| Search Metrics | API update to support a new optional param;include_full_channel |
| All APIs | General Performance Updates; no impact to the response or usuage of the API |
January
| API(s) Updated | Description |
|---|---|
| Social Ads | API update to suppot a new optional param;include_full_channel |
| All APIs | General Performance Updates; no impact to the response or usuage of the API |
| NA | Fix to reset campaign name to name of the current cycle. |
| Identity | General Performance Updates; no impact to the response or usuage of the API |
Table of Contents
APIs are split into 3 main sections:
Reporting Metric APIs: Performance metrics on your campaigns
Lead Info APIs/Webhooks: Lead information such as details, counts, and CRM integrations
Deprecated APIs: APIs that are deprecated and no longer updated or maintained
| Category | API to use | When you want |
|---|---|---|
| Identity | Identity | The identity endpoint is used to gain insight into the resources that are accessible by an advertiser. It will return advertisers that the user is authorized to retrieve data for, the active state of the advertisers, and the privilege details used to determine HIPAA access. |
| Campaigns | Campaigns & Cycles | List of campaigns and cycles for a given advertiser |
| Campaigns | Campaigns Overview | Total campaign performance metrics for all active campaigns in the last 30 days and basic metrics for all campaigns listed individually. This will include all types of campaign. It is best used as an “overview” |
| Campaigns | Campaigns Totals | Total lead count for all running campaigns type over the last 30 days |
| Display | Display Campaign Metrics | Detailed performance metrics for display campaigns including creatives metrics |
| Display | GeoFence Campaign Metrics | Detailed performance metrics for Geo Fence campaigns broken down by geofence and conversion fence |
| Search | Search Campaign Metrics | Detailed Performance metrics for search campaigns organized by campaigns. Includes device breakdown. |
| Search | Keyword Performance Metrics | Keywords with metrics on each of them for both search and site retargeting campaigns |
| Social | SocialAds Campaign Metrics | Detailed performance metrics for social campaigns (Facebook). Includes age, gender & device breakdown |
| Social | YouTube Campaign Metrics | Detailed performance metrics for social campaigns (You Tube) |
| XMO | XMO Campaign Metrics | Detailed performance metrics for Cross Media Optimization campaigns (XOM) |
| XMO | XMO Channel Metrics | Detailed performance metrics for Cross Media Optimization channels (XOM) |
| Traffic Metrics | Top referrer | Information on top referrers for both paid & organic traffic |
| Traffic Metrics | Total Track | Custom Tracking campaign metrics that have metrics on contacts from tracking phone number(s) and trackable URLs (Web & Phone) |
| Traffic Metrics | Web Event Metrics | Performance metric on pages that was selected as important by the advertiser; CVT or Web Events. Web Events can be pages that generate leads (Qualified web event) or pages that are informational and of value to the client (non-qualified web events) |
| Contact/Leads | Contacts | Contact information of every lead. HIPAA compatible; only authorized user will be able to retrieve data from this API. This API can be used for CRM integration purposes. |
| Contact/Leads | Contact Interactions | Contact information and interaction details of every lead. This API has ph call recording link, transcripts of emails, forms & chats. HIPAA compatible; only authorized user will be able to retrieve data from this API. This API can be used for CRM integration purposes. |
| Contact/Leads | CRM Webhooks | Self-service integration on Client Center through Edge. This web hook sends real time contact interaction details to receiver. This API can be used for CRM integration purposes. |
| Lead Metrics | Marketing Activity | Basic metrics organized by traffic; paid (LocaliQ & others) and organic |
| Lead Metrics | Chat Summary | Counts on chats received, types of changes from both LocaliQ and organic traffic |
| Lead Metrics | Lead Details | Lead (Calls, emails, web events, and chats) metric from all LocaliQ campaigns. This API also has number of calls broken down by call duration and time of day. This API does not have information on individual leads. Use the Contact and Contact Interactions API to retrieve details like name, transcripts, form information, etc. |
| Lead Metrics | LSA Campaigns | Local Service Ad Metrics by Campaign and Interval |
| Lead Metrics | LSA Campaign Rollup | Local Service Ads - Metric rollup by campaign |
| Lead Metrics | LSA Lead Details | Local Service Ads - Individual Leads for a date range |
| First Party Data | Capture External Events Confirmed Calls | First Party Data - Send LocaliQ high value call recording URLs |
| First Party Data | Capture External Events Chat | Local Service Ads - Send LocaliQ offline Chats that occur |
| Custom Integration | FranConnect/Franchise Management Software | If you are interested in this custom integration, please contact your account team (Offer #2095) |
Identity APIs
Identity API
The identity endpoint is used to gain insight into the resources that are accessible by an advertiser. It will return advertisers that the user is authorized to retrieve data for, the active state of the advertisers, and the privilege details used to determine HIPAA access.
Resource Overview
| Method | URI Format |
|---|---|
| GET | /identities/v3?[params] |
Usage
Get a list of advertisers filtered by query params. This endpoint also returns a list of possible business users that match the email address, in the case of multiple similar email addresses. The results of this query are cached for 15 minutes.
Parameters
| Param | Required | Description |
|---|---|---|
| user | Yes | Restricts the results to advertisers authorized for the given business user |
| business_id | No | The unique business id that this advertiser belongs to. |
| active_state | No | Array of active states that can include: 0: Advertiser not active. 1: Advertiser not active, but in grace period. 2: Advertiser is active |
| page | No | Return a specified page of results. Default value: 1 |
| page_size | No | Number of results per page Default value: 5000 |
Response Data Details
require 'uri'
require 'net/http'
url = URI("https://api.localiqservices.com/identities/v3?user=EMAIL_ADDRESS")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer OAUTH_ACCESS_TOKEN'
request["Accept"] = 'application/json'
response = http.request(request)
puts response.read_body
OkHttpClient client = new OkHttpClient();
Request request = new Request.Builder()
.url("https://api.localiqservices.com/identities/v3?user=EMAIL_ADDRESS")
.get()
.addHeader("Authorization", "Bearer OAUTH_ACCESS_TOKEN")
.addHeader("Accept", "application/json")
.build();
Response response = client.newCall(request).execute();
curl --request GET \
--url https://api.localiqservices.com/identities/v3?user=EMAIL_ADDRESS \
--header 'Accept: application/json' \
--header 'Authorization: Bearer OAUTH_ACCESS_TOKEN'
Example Response
https://api.localiqservices.com/identities/v3?user=test@test3.com
{
"bu_id": 1,
"user": "EMAIL_ADDRESS",
"business_id": 1,
"country": "USA",
"advertiser_count": 2,
"page": 1,
"page_size": 5000,
"authorized_advertisers": [
{
"name": "Test Advertiser 1",
"gmaid": "TEST_1",
"platform": "TEST",
"hipaa_protected": false,
"business_id": 1,
"business_name": "Test Name 1",
"business_user_id": 1,
"privilege_level": 3,
"advertiser_id": 1,
"active_state": 2,
"cobrand_id": 1123213,
"cobrand_name": "test"
},
{
"name": "Test Advertiser 2",
"gmaid": "TEST_2",
"platform": "TEST",
"hipaa_protected": true,
"business_id": 2,
"business_name": "Test Name 2",
"business_user_id": 2,
"privilege_level": 3,
"advertiser_id": 2,
"active_state": 2,
"cobrand_id": 1123213,
"cobrand_name": "test"
}
],
"users": [
{
"platform": "TEST",
"buid": 1,
"email": "EMAIL_ADDRESS",
"business_id": 2,
"name": "test",
"privilege_level": 3
}
]
}
curl --request GET \
--url https://api.localiqservices.com/identities/v3?user=EMAIL_ADDRESS&business_id=15 \
--header 'Accept: application/json' \
--header 'Authorization: Bearer OAUTH_ACCESS_TOKEN'
Example Response
https://api.localiqservices.com/identities/v3?user=test@test3.com
{
"bu_id": 1,
"user": "EMAIL_ADDRESS",
"business_id": 1,
"country": "USA",
"advertiser_count": 2,
"page": 1,
"page_size": 5000,
"authorized_advertisers": [
{
"name": "Test Advertiser 1",
"gmaid": "TEST_1",
"platform": "TEST",
"hipaa_protected": false,
"business_id": 15,
"business_name": "Test Name 1",
"business_user_id": 1,
"privilege_level": 3,
"advertiser_id": 1,
"active_state": 2,
"cobrand_id": 1123213,
"cobrand_name": "test"
},
{
"name": "Test Advertiser 2",
"gmaid": "TEST_2",
"platform": "TEST",
"hipaa_protected": true,
"business_id": 15,
"business_name": "Test Name 2",
"business_user_id": 2,
"privilege_level": 3,
"advertiser_id": 2,
"active_state": 2,
"cobrand_id": 1123213,
"cobrand_name": "test"
}
],
"users": [
{
"platform": "TEST",
"buid": 1,
"email": "EMAIL_ADDRESS",
"business_id": 2,
"name": "test",
"privilege_level": 3
}
]
}
curl --request GET \
--url https://api.localiqservices.com/identities/v3?user=EMAIL_ADDRESS&active_state[]=0 \
--header 'Accept: application/json' \
--header 'Authorization: Bearer OAUTH_ACCESS_TOKEN'
Example Response
https://api.localiqservices.com/identities/v3?user=test@test3.com
{
"bu_id": 1,
"user": "EMAIL_ADDRESS",
"business_id": 1,
"country": "USA",
"advertiser_count": 2,
"page": 1,
"page_size": 5000,
"authorized_advertisers": [
{
"name": "Test Advertiser 1",
"gmaid": "TEST_1",
"platform": "TEST",
"hipaa_protected": false,
"business_id": 1,
"business_name": "Test Name 1",
"business_user_id": 1,
"privilege_level": 3,
"advertiser_id": 1,
"active_state": 0,
"cobrand_id": 1123213,
"cobrand_name": "test"
},
{
"name": "Test Advertiser 2",
"gmaid": "TEST_2",
"platform": "TEST",
"hipaa_protected": true,
"business_id": 2,
"business_name": "Test Name 2",
"business_user_id": 2,
"privilege_level": 3,
"advertiser_id": 2,
"active_state": 0,
"cobrand_id": 1123213,
"cobrand_name": "test"
}
],
"users": [
{
"platform": "TEST",
"buid": 1,
"email": "EMAIL_ADDRESS",
"business_id": 2,
"name": "test",
"privilege_level": 3
}
]
}
The body of the API response will be a JSON object.
| Field Name | Datatype | Description |
|---|---|---|
| bu_id | Number | The unique business user id. |
| user | String | The email address of the business user. |
| business_id | Number | The unique business id that this business user belongs to. |
| country | String | The region that this business user belongs. |
| advertiser_count | String | The region that this business user belongs. |
| page | String | The region that this business user belongs. |
| page_size | String | The region that this business user belongs. |
| authorized_advertisers | Array | An array of JSON advertiser objects. |
| users | Array | An array of JSON user objects. |
Authorized Advertiser
| Advertiser Field Name | Datatype | Description |
|---|---|---|
| name | String | The name of the advertiser. |
| platform | String | The platform for the advertiser. |
| gmaid | String | The global master advertiser id of the advertiser. |
| hipaa_protected | String | The advertiser's HIPAA protection status |
| business_id | Number | The unique business id that this advertiser belongs to. |
| business_name | Number | The business name of this advertiser. |
| business_user_id | Number | The unique business_user id that is the primary user for this advertiser. |
| privilege_level | Number | privilege level. |
| advertiser_id | Number | The advertiser_id for this advertiser. Not necessarily the same as the numerical portion of the gmaid. |
| active_state | Number | 0: Advertiser not active. 1: Advertiser not active, but in grace period. 2: Advertiser is active. |
| cobrand_name | Number | Name given to a collection of of business or BID. This is an internal LocaliQ data construct used to aggregate like businesses e.g. partner, Gannett etc. |
| cobrand_id | Number | An ID used to uniquely identify a cobrand. |
User
| Advertiser Field Name | Datatype | Description |
|---|---|---|
| platform | String | The platform for the advertiser. |
| bu_id | Number | The unique business user id. |
| String | The global master advertiser id of the advertiser. | |
| business_id | Number | The unique business id that this business user belongs to. |
| name | String | The name of the user. |
| privilege_level | Number | privilege level of the business user. PL3 is required to access HIPAA protected data. |
Reporting Metric APIs
Campaigns APIs
Campaigns & Cycles
Resource Overview
| Method | URI Format |
|---|---|
| GET | /client_reports/campaigns/[gmaid]?[query_params] |
A list of filtered Campaigns, Campaign Cycles, and goals for a given report type and advertiser. (Cycles are not included for keyword_report)
If using the campaigns_overview report_type, all campaign data for the account will be provided including both Paid Media and Offer-based campaigns.
- Paid Media campaigns will include the associated
campaign_type. Paid Media campaigns include:- Chat
- Search
- Display
- TotalTrack
- YouTube
- CVT/Web Events
- Xmedia
- Shopping
- Offer-based campaigns include any campaign that is not Paid Media and will have a
campaign_typeofother. Examples of offer-based campaigns could be a Website or Client Center Organic Tracking campaign. - For search_activity, unified_display, and facebook_campaigns report_types, xmedia campaign types are included.
Parameters
When using the GET method, the results can be filtered using these parameters:
| Param | Required? | Function |
|---|---|---|
| report_type | Required | Only campaigns appropriate for this type of report will be returned. Allowed values are facebook_campaign, display_activity, search_activity, youtube, campaigns_overview, keyword, google_keyword, geofence_summary, cvt, wpc and addressable_geofence |
| global_master_campaign_id[] | Optional | Restrict results to one or more specific campaigns |
| campaign_status[] | Optional | Restrict results to campaigns with given status values. Allowed values are running, stopped and ended |
Response Data Details
Retrieve data for a specific report_type
curl -H "Authorization: Bearer OAUTH_ACCESS_TOKEN" \
"https://api.localiqservices.com/client_reports/campaigns/TEST_1?report_type=campaigns_overview
Retrieve data for a specific report_type as well as for running and stopped campaigns
curl -H "Authorization: Bearer OAUTH_ACCESS_TOKEN" \
"https://api.localiqservices.com/client_reports/campaigns/TEST_1?report_type=campaigns_overview&campaign_status[]=running,stopped
Example Response
{
"advertiser_name": "Advertiser (Demo)",
"advertiser_code": "demo",
"global_master_advertiser_id": "TEST_1",
"report_campaigns": [
{
"name": "Gannett Display Campaign (Demo)",
"global_master_campaign_id": "TEST_-25",
"campaign_type": "display",
"organization": "gannett",
"status": "running",
"has_addressable_geofence": true,
"has_cvt": false,
"has_video": false,
"offer_name": "Gannett Display",
"cycles": [
{
"campaign_cycle": "TEST_-26",
"start_date": "2020-10-10",
"end_date": null,
"name": "Gannett Display Campaign (Demo)"
}
],
"goals": [
{
"goal_type_id": 2,
"goal_type": "CPL"
}
]
},
{
"name": "Display Campaign (Demo)",
"global_master_campaign_id": "TEST_1",
"campaign_type": "display",
"organization": "reachlocal",
"status": "running",
"bidding_pricing_model_id": 8,
"has_addressable_geofence": false,
"has_cvt": true,
"has_video": true,
"offer_name": "Targeted Display",
"cycles": [
{
"campaign_cycle": "TEST_2",
"start_date": "2020-10-10",
"end_date": null,
"name": "Display Campaign (Demo)"
}
],
"goals": [
{
"goal_type_id": 2,
"goal_type": "CPL"
}
]
},
{
"name": "Search Campaign (Demo)",
"global_master_campaign_id": "TEST_4",
"campaign_type": "search",
"organization": "reachlocal",
"status": "running",
"has_addressable_geofence": false,
"has_cvt": true,
"has_video": true,
"offer_name": "Search Engine Marketing",
"cycles": [
{
"campaign_cycle": "TEST_5",
"start_date": "2020-10-10",
"end_date": null,
"name": "Search Campaign (Demo)"
}
],
"goals": []
},
{
"name": "Chat Campaign (Demo)",
"global_master_campaign_id": "TEST_19",
"campaign_type": "chat",
"organization": "reachlocal",
"status": "running",
"has_addressable_geofence": false,
"has_cvt": true,
"has_video": false,
"offer_name": "Live Chat",
"cycles": [
{
"campaign_cycle": "TEST_20",
"start_date": "2020-10-10",
"end_date": null,
"name": "Chat Campaign (Demo)"
}
],
"goals": [
{
"goal_type_id": 2,
"goal_type": "CPL"
}
]
},
{
"name": "Facebook Campaign (Demo)",
"global_master_campaign_id": "TEST_22",
"campaign_type": "facebook",
"organization": "reachlocal",
"status": "running",
"has_addressable_geofence": false,
"has_cvt": false,
"has_video": false,
"offer_name": null,
"cycles": [
{
"campaign_cycle": "TEST_23",
"start_date": "2020-10-10",
"end_date": null,
"name": "Facebook Campaign (Demo)"
}
],
"goals": [
{
"goal_type_id": 2,
"goal_type": "CPL"
}
]
},
{
"name": "Geofence Campaign (Demo)",
"global_master_campaign_id": "TEST_28",
"campaign_type": "display",
"organization": "reachlocal",
"status": "running",
"has_addressable_geofence": false,
"has_cvt": false,
"has_video": false,
"offer_name": "ReachDisplay GeoFence",
"cycles": [
{
"campaign_cycle": "TEST_29",
"start_date": "2020-10-10",
"end_date": null,
"name": "Geofence Campaign (Demo)"
}
],
"goals": [
{
"goal_type_id": 2,
"goal_type": "CPL"
}
]
},
{
"name": "Youtube Campaign (Demo)",
"global_master_campaign_id": "TEST_31",
"campaign_type": "youtube",
"organization": "reachlocal",
"status": "running",
"has_addressable_geofence": false,
"has_cvt": false,
"has_video": false,
"offer_name": "YouTube Advertising",
"cycles": [
{
"campaign_cycle": "TEST_32",
"start_date": "2020-10-10",
"end_date": null,
"name": "Youtube Campaign (Demo)"
}
],
"goals": [
{
"goal_type_id": 2,
"goal_type": "CPL"
}
]
},
{
"name": "Xmedia Campaign (Demo)",
"global_master_campaign_id": "TEST_37",
"campaign_type": "xmedia",
"organization": "reachlocal",
"status": "running",
"has_addressable_geofence": false,
"has_cvt": false,
"has_video": false,
"cycles": [
{
"campaign_cycle": "TEST_38",
"start_date": "2020-10-10",
"end_date": null,
"name": "Xmedia Campaign (Demo)"
}
],
"goals": [
{
"goal_type_id": 2,
"goal_type": "CPL"
}
]
},
{
"name": "Email Campaign (Demo)",
"global_master_campaign_id": "TEST_33",
"campaign_type": "email",
"organization": "reachlocal",
"status": "running",
"has_addressable_geofence": false,
"has_cvt": false,
"has_video": false,
"cycles": [
{
"campaign_cycle": "TEST_34",
"start_date": "2020-10-10",
"end_date": null,
"name": "Email Campaign (Demo)"
}
],
"goals": [
{
"goal_type_id": 2,
"goal_type": "CPL"
}
]
},
{
"name":"Shopping Campaign (Demo)",
"global_master_campaign_id":"TEST_73432",
"campaign_type":"shopping",
"organization":"reachlocal",
"status":"running",
"has_addressable_geofence":false,
"has_cvt":false,"has_video":false,
"offer_name":"Shopping","off_platform_activity":false,
"cycles":[
{"campaign_cycle":"TEST_73433",
"start_date":"2023-04-13",
"end_date":null,
"name":"Shopping Campaign (Demo)"
}
]
}
]
}
| Field Name | Datatype | Description |
|---|---|---|
| advertiser_name | String | Name of advertiser |
| advertiser_code | String | Non-unique identifier used for internal purposes |
| global_master_advertiser_id | String | Identifier for advertiser |
| report_campaigns | Object | Report Campaigns Object |
| Field Name | Datatype | Description |
|---|---|---|
| name | String | Name of campaign |
| global_master_campaign_id | String | Identifier for campaign |
| campaign_type | String | Type of campaign |
| organization | String | Organization |
| status | String | Status of campaign |
| bidding_pricing_model_id | Integer | The id which will be used to filter the sub type of top search campaign (shown only for search campaigns) |
| has_addressable_geofence | Boolean | True or False |
| has_cvt | Boolean | True or False |
| has_video | Boolean | True or False |
| offer_name | String | Campaign offer name |
| cycles | Object | Cycles Object |
| goals | Object | Goals Object |
| Field Name | Datatype | Description |
|---|---|---|
| campaign_cycle | String | Identifier for campaign cycle |
| start_date | String | Start date of campaign cycle |
| end_date | String | End date of campaign cycle |
| name | String | Name of campaign cycle |
| Field Name | Datatype | Description |
|---|---|---|
| goal_type_id | String | Identifier for campaign goal type |
| goal_type | String | Name(Type) of goal type |
Campaigns Overview
Resource Overview
| Method | URI Format |
|---|---|
| GET | /client_reports/campaigns_overview/[gmaid] |
Use GET to retrieve the Campaigns Overview Report,
The data returned will include campaign performance metrics for the last 30 days and a campaign list with additional details and breakdowns per cycle. Campaign are limited to those that have had activity within the previous year. This means that a campaign that ended 13 months prior will not be included in the campaign list section.
The performance metrics for the last 30 days are across all running campaigns and will include:
- Total Impressions
- Total Clicks
- Total Calls
- Total Emails
- Total Web Events
- Total Qualified Web Events
- Total Chat Events
The campaign list section will list all (running, stopped and ended) campaigns with the following information for each campaign in the list:
- Campaign Name
- Campaign ID (global_master_campaign_id)
- Campaign Type
- Source
- Currency
- Start Date
- End Date
- Status
- A List of Cycles with:
- Cycle ID
- Start Date
- End Date
- Number of Impressions
- Number of Clicks
- Number of Leads
- Spend
- Budget Amount
- Opens for Email Campaigns
All campaign data for the account will be provided including both Paid Media and Offer-based campaigns.
- Paid Media campaigns will include the associated
campaign_type. Paid Media campaigns include:- Chat
- Search
- Display
- TotalTrack
- YouTube
- CVT/Web Events
- Shopping
- Offer-based campaigns include any campaign that is not Paid Media and will have a
campaign_typeofother. Examples of offer-based campaigns could be a Website or Client Center Organic Tracking campaign.
Parameters
None
Response Data Details
The following command returns an example JSON structure:
curl -H "Authorization: Bearer OAUTH_ACCESS_TOKEN" \
"https://api.localiqservices.com/client_reports/campaigns_overview/TEST_1"
Example Response
{
"report_type": "campaigns_overview",
"report_date": "2020-11-05",
"start_date": "2019-11-05",
"end_date": "2020-11-05",
"time_zone": "America/Los_Angeles",
"currency": "USD",
"report_data": {
"campaigns": [
{
"name": "Email Campaign (Demo)",
"global_master_campaign_id": "TEST_7025",
"type": "email",
"source": "Targeted Email",
"start_date": "2020-10-15",
"end_date": null,
"status": "running",
"cycles": [
{
"campaign_cycle": "TEST_7034",
"start_date": "2020-10-15",
"end_date": "2020-11-03",
"clicks": 731,
"leads": 631,
"spend": 500.0,
"budget": 500.0,
"opens": 1449
}
]
},
{
"name": "Lsa Campaign (Demo)",
"global_master_campaign_id": "TEST_7008",
"type": "lsa",
"source": "Local Services Ads",
"start_date": "2020-10-15",
"end_date": null,
"status": "running",
"cycles": [
{
"campaign_cycle": "TEST_7015",
"start_date": "2020-10-15",
"end_date": "2020-11-03",
"impressions": 0,
"clicks": 0,
"leads": 0,
"spend": 500.0,
"budget": 500.0
}
]
},
{
"name": "Xmedia Campaign (Demo)",
"global_master_campaign_id": "TEST_6954",
"type": "xmedia",
"source": "Omnichannel - Smart",
"start_date": "2020-10-15",
"end_date": null,
"status": "running",
"cycles": [
{
"campaign_cycle": "TEST_6963",
"start_date": "2020-10-15",
"end_date": "2020-11-03",
"impressions": 26209,
"clicks": 322,
"leads": 629,
"spend": 500.0,
"budget": 500.0
}
]
},
{
"name": "Email Campaign (Demo)",
"global_master_campaign_id": "TEST_207085",
"type": "email",
"source": "Targeted Email",
"start_date": "2020-10-10",
"end_date": null,
"status": "running",
"cycles": [
{
"campaign_cycle": "TEST_207086",
"start_date": "2020-10-10",
"end_date": null,
"impressions": 3568,
"clicks": 56,
"leads": 83,
"spend": 75.0,
"budget": 500.0,
"quantity": 50000,
"views": 6591,
"opens": 6591
}
]
},
{
"name": "Youtube Campaign (Demo)",
"global_master_campaign_id": "TEST_6938",
"type": "youtube",
"source": "YouTube Advertising",
"start_date": "2020-10-15",
"end_date": null,
"status": "running",
"cycles": [
{
"campaign_cycle": "TEST_6942",
"start_date": "2020-10-15",
"end_date": "2020-11-03",
"impressions": 26978,
"clicks": 325,
"leads": 624,
"spend": 500.0,
"budget": 500.0
}
]
},
{
"name": "Geofence Campaign (Demo)",
"global_master_campaign_id": "TEST_6934",
"type": "display",
"source": "ReachDisplay GeoFence",
"start_date": "2020-10-15",
"end_date": null,
"status": "running",
"cycles": [
{
"campaign_cycle": "TEST_6936",
"start_date": "2020-10-15",
"end_date": "2020-11-03",
"impressions": 26598,
"clicks": 309,
"leads": 640,
"spend": 500.0,
"budget": 500.0
}
]
},
{
"name": "Facebook Campaign (Demo)",
"global_master_campaign_id": "TEST_6921",
"type": "facebook",
"source": "Facebook",
"start_date": "2020-10-15",
"end_date": null,
"status": "running",
"cycles": [
{
"campaign_cycle": "TEST_6922",
"start_date": "2020-10-15",
"end_date": "2020-11-03",
"impressions": 25288,
"clicks": 304,
"leads": 640,
"spend": 500.0,
"budget": 500.0
}
]
},
{
"name": "Chat Campaign (Demo)",
"global_master_campaign_id": "TEST_6918",
"type": "chat",
"source": "Live Chat",
"start_date": "2020-10-15",
"end_date": null,
"status": "running",
"cycles": [
{
"campaign_cycle": "TEST_6919",
"start_date": "2020-10-15",
"end_date": "2020-11-03",
"impressions": 27323,
"clicks": 332,
"leads": 638,
"spend": 500.0,
"budget": 500.0
}
]
},
{
"name": "Other Campaign (Demo)",
"global_master_campaign_id": "TEST_6915",
"type": "other",
"source": "Organic Traffic",
"start_date": "2020-10-15",
"end_date": null,
"status": "running",
"cycles": [
{
"campaign_cycle": "TEST_6916",
"start_date": "2020-10-15",
"end_date": "2020-11-03",
"impressions": 26601,
"clicks": 332,
"leads": 627,
"spend": 500.0,
"budget": 500.0
}
]
},
{
"name": "Totaltrack Web Campaign (Demo)",
"global_master_campaign_id": "TEST_6912",
"type": "totaltrack",
"source": "Campaign Tracking Only (TotalTrack)",
"start_date": "2020-10-15",
"end_date": null,
"status": "running",
"cycles": [
{
"campaign_cycle": "TEST_6913",
"start_date": "2020-10-15",
"end_date": "2020-11-03",
"impressions": 25728,
"clicks": 326,
"leads": 634,
"spend": 500.0,
"budget": 500.0
}
]
},
{
"name": "Totaltrack Web Phone Campaign (Demo)",
"global_master_campaign_id": "TEST_6909",
"type": "totaltrack",
"source": "Campaign Tracking Only (TotalTrack)",
"start_date": "2020-10-15",
"end_date": null,
"status": "running",
"cycles": [
{
"campaign_cycle": "TEST_6910",
"start_date": "2020-10-15",
"end_date": "2020-11-03",
"impressions": 25202,
"clicks": 312,
"leads": 634,
"spend": 500.0,
"budget": 500.0
}
]
},
{
"name": "Totaltrack Phone Campaign (Demo)",
"global_master_campaign_id": "TEST_6906",
"type": "totaltrack",
"source": "Campaign Tracking Only (TotalTrack)",
"start_date": "2020-10-15",
"end_date": null,
"status": "running",
"cycles": [
{
"campaign_cycle": "TEST_6907",
"start_date": "2020-10-15",
"end_date": "2020-11-03",
"impressions": 26799,
"clicks": 323,
"leads": 626,
"spend": 500.0,
"budget": 500.0
}
]
},
{
"name": "Search Campaign (Demo)",
"global_master_campaign_id": "TEST_6903",
"type": "search",
"source": "Search Engine Marketing",
"start_date": "2020-10-15",
"end_date": null,
"status": "running",
"bidding_pricing_model_id": 8,
"cycles": [
{
"campaign_cycle": "TEST_6904",
"start_date": "2020-10-15",
"end_date": "2020-11-03",
"impressions": 26329,
"clicks": 335,
"leads": 613,
"spend": 500.0,
"budget": 500.0
}
]
},
{
"name": "Display Campaign (Demo)",
"global_master_campaign_id": "TEST_6900",
"type": "display",
"source": "Targeted Display",
"start_date": "2020-10-15",
"end_date": null,
"status": "running",
"cycles": [
{
"campaign_cycle": "TEST_6901",
"start_date": "2020-10-15",
"end_date": "2020-11-03",
"impressions": 25701,
"clicks": 309,
"leads": 614,
"spend": 500.0,
"budget": 500.0
}
]
},
{
"name": "Gannett Display Campaign (Demo)",
"global_master_campaign_id": "TEST_-6924",
"type": "gannett_display",
"source": "Gannett Display",
"start_date": "2020-10-15",
"end_date": null,
"status": "running",
"cycles": [
{
"campaign_cycle": "TEST_-6925",
"start_date": "2020-10-15",
"end_date": null,
"impressions": 26743,
"clicks": 332,
"leads": null,
"spend": 0.0,
"budget": 0.0
}
]
},
{
"name":"Shopping Campaign (Demo)",
"global_master_campaign_id":"TEST_73432",
"type":"shopping",
"source":"Shopping",
"start_date":"2023-04-13",
"end_dat": null,
"status":"running",
"cycles":[
{
"campaign_cycle":"TEST_73433",
"start_date":"2023-04-13",
"end_date":null,
"impressions": 0,
"clicks": 0,
"leads": null,
"spend": 0.0,
"budget": 0.0
}
]
}
],
"totals": {
"calls": 1921,
"chats": 1861,
"clicks": 3861,
"emails": 1877,
"web_events": 1891,
"impressions": 315499,
"qualified_web_events": 1291
}
},
"global_master_advertiser_id": "TEST_1"
}
| Field Name | Datatype | Description |
|---|---|---|
| report_type | String | Type of report |
| report_date | String | Date report ran |
| start_date | String | Start Date |
| end_date | String | End Date |
| time_zone | String | Time Zone of Data |
| currency | String | Currency of report |
| report_data | Object | Report Data Object |
| global_master_advertiser_id | String | Identifier for advertiser |
| Field Name | Datatype | Description |
|---|---|---|
| totals | Object | Object of totals details. Totals Object |
| campaigns | Array | Array of campaigns with campaign details. Campaigns Object |
Totals Object (Running campaign performance totals for the last 30 days )
| Field Name | Datatype | Description |
|---|---|---|
| impressions | Integer | Total impressions |
| clicks | Integer | Total click events |
| calls | Integer | Total call events |
| emails | Integer | Total email events |
| web_events | Integer | Total web events |
| qualified_web_events | Integer | Total lead generating CVT or Web Event |
| chats | Integer | Total chat generated by paid traffic |
| Field Name | Datatype | Description |
|---|---|---|
| name | String | Campaign name |
| global_master_campaign_id | String | Identifier for campaign |
| type | String | Type of campaign |
| source | String | Source of campaign |
| currency | String | Type of currency used |
| start_date | String | Start date for campaign |
| end_date | String | End date for campaign |
| status | String | campaign status |
| bidding_pricing_model_id | Integer | The id which will be used to filter the sub type of top search campaign (shown only for search campaigns) |
| cycles | Object | Data for cycles. Cycles Object |
| Field Name | Datatype | Description |
|---|---|---|
| campaign_cycle | String | Identifier for cycle |
| start_date | String | Start date for cycle |
| end_date | String | End date for cycle |
| impressions | Integer | Total Impressions for cycle (N/A for Email Campaigns) |
| clicks | Integer | Total Clicks for cycle |
| leads | Integer | Total Leads for cycle |
| spend | Integer | Total Spend/Cost of cycle |
| budget | Integer | Total Budget of cycle |
| opens | Integer | Total Opens for cycle (Email Campaigns Only) |
| quantity | Integer | Total Quantity for cycle. (Email Campaigns Only) |
| views | Integer | Total Views of cycle. (Email Campaigns Only) |
Campaigns Totals
Resource Overview
| Method | URI Format |
|---|---|
| GET | /client_reports/campaigns_totals/[gmaid] |
The data returned will include count of running campaigns and leads for all campaign types over the last 30 days.
Parameters
None
Response Data Details
The following command returns an example JSON structure:
curl -H "Authorization: Bearer OAUTH_ACCESS_TOKEN" \
"https://api.localiqservices.com/client_reports/campaigns_totals/TEST_1"
Example Response
{
"report_type": "campaigns_totals",
"report_date": "2020-10-12",
"start_date": "2020-09-12",
"end_date": "2020-10-12",
"time_zone": "America/Los_Angeles",
"report_data": {
"campaigns": 13,
"leads": 1009
},
"global_master_advertiser_id": "TEST_1"
}
| Field Name | Datatype | Description |
|---|---|---|
| report_type | String | Type of report |
| report_date | String | Date report ran |
| start_date | String | Start Date |
| end_date | String | End Date |
| time_zone | String | Time Zone of Data |
| report_data | Object | ReportData Object |
| global_master_advertiser_id | String | Identifier for advertiser |
ReportData Object
| Field Name | Datatype | Description |
|---|---|---|
| campaigns | String | Total running campaigns |
| leads | String | Total leads for all campaigns |
Display APIs
Display Campaign Metrics
Resource Overview
| Method | URI Format |
|---|---|
| GET | /client_reports/unified_display/[gmaid]?[query_params] |
This is a Display Metrics API that can be used by customers that have Display campaigns from either the LocaliQ or Gannett brand. Data is returned for a GMAID for a specific date range determined by start_date and end_date. Data can also be returned in specified intervals by using the interval_size param. The requirements for these parameters are described below. All metrics are reported at the creative level, and aggregated at the Interval/Campaign level for LocaliQ brand or Line Item level for the Gannett brand. When data is unavailable, corresponding property will not be present in the response. For example, if we do not have data for a creative_type or creative_size, it will not be present in the response.
Note: Please note in some cases, the response might not have all of the creatives used in the campaign. This scenario is apparent when the total metrics for the campaign does not match the sum of the same metrics across every creative within the campaigns.
We recommend you use the campaign totals from the response when reporting at the campaign level since it will include the creatives that may be missing in the response.
Note: We recommend that users migrate to this API instead of using the Display Activity API and Display Creative API, as they will no longer be updated.
Note: MOAT metrics are not supported after December 31, 2019. Any requests for date ranges after this will not include MOAT metrics. Date ranges that span beyond December 31, 2019 will show calculations based on start_date through December 31, 2019.
Parameters
When using the GET method, the results can be filtered using these parameters:
| Parameter | Required | Description |
|---|---|---|
| start_date | Yes | Restricts the results to those occurring on or after this date |
| end_date | Yes | Restricts the results to those occurring on or before this date |
| interval_size | No | Specifies the type of interval: none, day, calendar_week, or calendar_month Default value: none |
| global_master_campaign_id[] | Restrict results to one or more specific campaigns. This should be a comma separated string. Ex: global_master_campaign_id[]=TEST_1,TEST_2 | |
| campaign_cycle | Restrict results to a single campaign cycle | |
| campaign_status[] | Restrict results to all campaigns with given status values. Allowed values are running, stopped and ended. This should be a comma separated string. Ex: campaign_status[]=running,stopped | |
| campaign_type[] | Restrict results to all campaigns of given type. Valid values are display, gannett_display, xmedia | |
| include_full_channel | Optional, default: false. Includes all metrics for the display channel. Xmedia campaigns will only contain metrics that belong to the display channel, rather than full campaign metrics. |
Response Data Details
Retrieve data for a specific range of dates
curl -H "Authorization: Bearer OAUTH_ACCESS_TOKEN" \
https://api.localiqservices.com/client_reports/unified_display/TEST_1?start_date=2016-12-01&end_date=2016-12-31
Retrieve data with intervals
curl -H "Authorization: Bearer OAUTH_ACCESS_TOKEN" \
https://api.localiqservices.com/client_reports/unified_display/TEST_1?start_date=2016-12-01&end_date=2016-12-31&interval_size=day
Example Response
{
"api_name": "unified_display",
"api_run_date": "2020-12-18",
"earliest_date_available": "2020-11-01",
"start_date": "2020-12-12",
"end_date": "2020-12-13",
"time_zone": "America/Los_Angeles",
"interval_size": "day",
"currency": "USD",
"global_master_advertiser_id": "TEST_1",
"advertiser_name": "Advertiser (Demo)",
"report_data": {
"totals": {
"clicks": 152.0,
"impressions": 13560.0,
"ctr": 1.12,
"video_full_screen": 43.0,
"video_mute": 20.0,
"video_unmute": 33.0,
"video_pause": 20.0,
"video_resume": 33.0,
"video_views": 71.0,
"total_conversions": 90.0,
"click_through_conversions": 64.0,
"view_through_conversions": 107.0,
"video_played_to_25_pct": 23.0,
"video_played_to_50_pct": 33.0,
"video_played_to_75_pct": 43.0,
"completed_views": 53.0,
"video_complete_rate": 74.65,
"view_thru_rate": 0.39
},
"intervals": [
{
"start_date": "2020-12-12",
"clicks": 75.0,
"impressions": 6882.0,
"ctr": 1.09,
"video_full_screen": 20.0,
"video_mute": 10.0,
"video_unmute": 15.0,
"video_pause": 10.0,
"video_resume": 15.0,
"video_views": 34.0,
"total_conversions": 40.0,
"click_through_conversions": 37.0,
"view_through_conversions": 38.0,
"video_played_to_25_pct": 10.0,
"video_played_to_50_pct": 15.0,
"video_played_to_75_pct": 20.0,
"completed_views": 25.0,
"video_complete_rate": 73.53,
"view_thru_rate": 0.36
},
{
"start_date": "2020-12-13",
"clicks": 77.0,
"impressions": 6678.0,
"ctr": 1.15,
"video_full_screen": 23.0,
"video_mute": 10.0,
"video_unmute": 18.0,
"video_pause": 10.0,
"video_resume": 18.0,
"video_views": 37.0,
"total_conversions": 50.0,
"click_through_conversions": 27.0,
"view_through_conversions": 69.0,
"video_played_to_25_pct": 13.0,
"video_played_to_50_pct": 18.0,
"video_played_to_75_pct": 23.0,
"completed_views": 28.0,
"video_complete_rate": 75.68,
"view_thru_rate": 0.42
}
],
"campaigns": [
{
"name": "Display Campaign (Demo)",
"global_master_campaign_id": "TEST_1932587",
"organization": "reachlocal",
"start_date": "2020-11-01",
"end_date": null,
"type": "display",
"status": "running",
"spend": 50.0,
"impressions": 2649.0,
"clicks": 31.0,
"form_submissions_ct": 15.0,
"form_submissions_vt": 28.0,
"priority_page_views_ct": 19.0,
"priority_page_views_vt": 14.0,
"website_visits_vt": 13.0,
"walk_ins": 0.0,
"ctr": 1.17,
"cpm": 18.88,
"cpc": 1.61,
"cost_per_submission": 1.16,
"div": 44.0,
"cpdiv": 1.14,
"video_full_screen": 11.0,
"video_mute": 4.0,
"video_unmute": 9.0,
"video_pause": 4.0,
"video_resume": 9.0,
"video_views": 11.0,
"total_conversions": 18.0,
"click_through_conversions": 44.0,
"view_through_conversions": 55.0,
"video_played_to_25_pct": 7.0,
"video_played_to_50_pct": 9.0,
"video_played_to_75_pct": 11.0,
"completed_views": 13.0,
"video_complete_rate": 118.18,
"view_thru_rate": 0.49,
"cost_per_view": 3.85,
"intervals": [
{
"start_date": "2020-12-12",
"spend": 25.0,
"impressions": 1292.0,
"clicks": 11.0,
"form_submissions_ct": 6.0,
"form_submissions_vt": 12.0,
"priority_page_views_ct": 10.0,
"priority_page_views_vt": 5.0,
"website_visits_vt": 5.0,
"walk_ins": 0.0,
"ctr": 0.85,
"cpm": 19.35,
"cpc": 2.27,
"cost_per_submission": 1.39,
"div": 16.0,
"cpdiv": 1.56,
"video_full_screen": 4.0,
"video_mute": 2.0,
"video_unmute": 3.0,
"video_pause": 2.0,
"video_resume": 3.0,
"video_views": 6.0,
"total_conversions": 8.0,
"click_through_conversions": 21.0,
"view_through_conversions": 22.0,
"video_played_to_25_pct": 2.0,
"video_played_to_50_pct": 3.0,
"video_played_to_75_pct": 4.0,
"completed_views": 5.0,
"video_complete_rate": 83.33,
"view_thru_rate": 0.39,
"cost_per_view": 5.0
},
{
"start_date": "2020-12-13",
"spend": 25.0,
"impressions": 1357.0,
"clicks": 20.0,
"form_submissions_ct": 9.0,
"form_submissions_vt": 16.0,
"priority_page_views_ct": 9.0,
"priority_page_views_vt": 9.0,
"website_visits_vt": 8.0,
"walk_ins": 0.0,
"ctr": 1.47,
"cpm": 18.42,
"cpc": 1.25,
"cost_per_submission": 1.0,
"div": 28.0,
"cpdiv": 0.89,
"video_full_screen": 7.0,
"video_mute": 2.0,
"video_unmute": 6.0,
"video_pause": 2.0,
"video_resume": 6.0,
"video_views": 5.0,
"total_conversions": 10.0,
"click_through_conversions": 23.0,
"view_through_conversions": 33.0,
"video_played_to_25_pct": 5.0,
"video_played_to_50_pct": 6.0,
"video_played_to_75_pct": 7.0,
"completed_views": 8.0,
"video_complete_rate": 160.0,
"view_thru_rate": 0.59,
"cost_per_view": 3.13
}
],
"creatives": [
{
"creative_id": 1,
"publisher_id": 49,
"publisher_name": "Simpli.fi API",
"creative_name": "Creative (Demo) 1",
"creative_type": "Image",
"creative_size": "300x250",
"creative_template_id": 1234,
"native_style_id": 5678 ,
"preview_url": "https://example.com/imgUpload128240714.png",
"spend": 29.82,
"impressions": 1442.0,
"clicks": 13.0,
"form_submissions_ct": 3.0,
"form_submissions_vt": 22.0,
"priority_page_views_ct": 6.0,
"priority_page_views_vt": 11.0,
"website_visits_vt": 4.0,
"walk_ins": 0.0,
"ctr": 0.9,
"cpm": 20.68,
"cpc": 2.29,
"cost_per_submission": 1.19,
"div": 17.0,
"cpdiv": 1.75,
"video_full_screen": 7.0,
"video_mute": 3.0,
"video_unmute": 4.0,
"video_pause": 3.0,
"video_resume": 3.0,
"video_views": 5.0,
"total_conversions": 6.0,
"click_through_conversions": 14.0,
"view_through_conversions": 37.0,
"video_played_to_25_pct": 5.0,
"video_played_to_50_pct": 4.0,
"video_played_to_75_pct": 6.0,
"completed_views": 7.0,
"video_complete_rate": 140.0,
"view_thru_rate": 0.49,
"cost_per_view": 4.26,
"intervals": [
{
"start_date": "2020-12-12",
"spend": 5.46,
"impressions": 312.0,
"clicks": 11.0,
"form_submissions_ct": 1.0,
"form_submissions_vt": 9.0,
"priority_page_views_ct": 3.0,
"priority_page_views_vt": 4.0,
"website_visits_vt": 1.0,
"walk_ins": 0.0,
"ctr": 3.53,
"cpm": 17.5,
"cpc": 0.5,
"cost_per_submission": 0.55,
"div": 12.0,
"cpdiv": 0.46,
"video_full_screen": 2.0,
"video_mute": 1.0,
"video_unmute": 3.0,
"video_pause": 1.0,
"video_resume": 1.0,
"video_views": 2.0,
"total_conversions": 2.0,
"click_through_conversions": 7.0,
"view_through_conversions": 14.0,
"video_played_to_25_pct": 2.0,
"video_played_to_50_pct": 2.0,
"video_played_to_75_pct": 4.0,
"completed_views": 1.0,
"video_complete_rate": 50.0,
"view_thru_rate": 0.32,
"cost_per_view": 5.46
},
{
"start_date": "2020-12-13",
"spend": 24.37,
"impressions": 1130.0,
"clicks": 2.0,
"form_submissions_ct": 2.0,
"form_submissions_vt": 13.0,
"priority_page_views_ct": 3.0,
"priority_page_views_vt": 7.0,
"website_visits_vt": 3.0,
"walk_ins": 0.0,
"ctr": 0.18,
"cpm": 21.57,
"cpc": 12.19,
"cost_per_submission": 1.62,
"div": 5.0,
"cpdiv": 4.87,
"video_full_screen": 5.0,
"video_mute": 2.0,
"video_unmute": 1.0,
"video_pause": 2.0,
"video_resume": 2.0,
"video_views": 3.0,
"total_conversions": 4.0,
"click_through_conversions": 7.0,
"view_through_conversions": 23.0,
"video_played_to_25_pct": 3.0,
"video_played_to_50_pct": 2.0,
"video_played_to_75_pct": 2.0,
"completed_views": 6.0,
"video_complete_rate": 200.0,
"view_thru_rate": 0.53,
"cost_per_view": 4.06
}
]
},
{
"creative_id": 2,
"publisher_id": 49,
"publisher_name": "Simpli.fi API",
"creative_name": "Creative (Demo) 2",
"creative_type": "Image",
"creative_template_id": 1234,
"native_style_id": 5678 ,
"creative_size": "300x250",
"spend": 20.18,
"impressions": 1207.0,
"clicks": 18.0,
"form_submissions_ct": 12.0,
"form_submissions_vt": 6.0,
"priority_page_views_ct": 13.0,
"priority_page_views_vt": 3.0,
"website_visits_vt": 9.0,
"walk_ins": 0.0,
"ctr": 1.49,
"cpm": 16.72,
"cpc": 1.12,
"cost_per_submission": 1.12,
"div": 27.0,
"cpdiv": 0.75,
"video_full_screen": 4.0,
"video_mute": 1.0,
"video_unmute": 5.0,
"video_pause": 1.0,
"video_resume": 6.0,
"video_views": 6.0,
"total_conversions": 12.0,
"click_through_conversions": 30.0,
"view_through_conversions": 18.0,
"video_played_to_25_pct": 2.0,
"video_played_to_50_pct": 5.0,
"video_played_to_75_pct": 5.0,
"completed_views": 6.0,
"video_complete_rate": 100.0,
"view_thru_rate": 0.5,
"cost_per_view": 3.36,
"intervals": [
{
"start_date": "2020-12-12",
"spend": 19.54,
"impressions": 980.0,
"clicks": 0.0,
"form_submissions_ct": 5.0,
"form_submissions_vt": 3.0,
"priority_page_views_ct": 7.0,
"priority_page_views_vt": 1.0,
"website_visits_vt": 4.0,
"walk_ins": 0.0,
"ctr": 0.0,
"cpm": 19.94,
"cpc": 0,
"cost_per_submission": 2.44,
"div": 4.0,
"cpdiv": 4.89,
"video_full_screen": 2.0,
"video_mute": 1.0,
"video_unmute": 0.0,
"video_pause": 1.0,
"video_resume": 2.0,
"video_views": 4.0,
"total_conversions": 6.0,
"click_through_conversions": 14.0,
"view_through_conversions": 8.0,
"video_played_to_25_pct": 0.0,
"video_played_to_50_pct": 1.0,
"video_played_to_75_pct": 0.0,
"completed_views": 4.0,
"video_complete_rate": 100.0,
"view_thru_rate": 0.41,
"cost_per_view": 4.89
},
{
"start_date": "2020-12-13",
"spend": 0.63,
"impressions": 227.0,
"clicks": 18.0,
"form_submissions_ct": 7.0,
"form_submissions_vt": 3.0,
"priority_page_views_ct": 6.0,
"priority_page_views_vt": 2.0,
"website_visits_vt": 5.0,
"walk_ins": 0.0,
"ctr": 7.93,
"cpm": 2.78,
"cpc": 0.04,
"cost_per_submission": 0.06,
"div": 23.0,
"cpdiv": 0.03,
"video_full_screen": 2.0,
"video_mute": 0.0,
"video_unmute": 5.0,
"video_pause": 0.0,
"video_resume": 4.0,
"video_views": 2.0,
"total_conversions": 6.0,
"click_through_conversions": 16.0,
"view_through_conversions": 10.0,
"video_played_to_25_pct": 2.0,
"video_played_to_50_pct": 4.0,
"video_played_to_75_pct": 5.0,
"completed_views": 2.0,
"video_complete_rate": 100.0,
"view_thru_rate": 0.88,
"cost_per_view": 0.32
}
]
}
]
},
{
"name": "Facebook Campaign (Demo)",
"global_master_campaign_id": "TEST_1932611",
"organization": "reachlocal",
"start_date": "2020-11-01",
"end_date": null,
"type": "facebook",
"status": "running",
"spend": 50.0,
"impressions": 2722.0,
"clicks": 23.0,
"form_submissions_ct": 0.0,
"form_submissions_vt": 0.0,
"priority_page_views_ct": 0.0,
"priority_page_views_vt": 0.0,
"website_visits_vt": 0.0,
"walk_ins": 0.0,
"ctr": 0.84,
"cpm": 18.37,
"cpc": 2.17,
"cost_per_submission": 0,
"div": 0.0,
"cpdiv": 0,
"video_full_screen": 0.0,
"video_mute": 0.0,
"video_unmute": 0.0,
"video_pause": 0.0,
"video_resume": 0.0,
"video_views": 0.0,
"total_conversions": 0.0,
"click_through_conversions": 0.0,
"view_through_conversions": 0.0,
"video_played_to_25_pct": 0.0,
"video_played_to_50_pct": 0.0,
"video_played_to_75_pct": 0.0,
"completed_views": 0.0,
"video_complete_rate": 0.0,
"view_thru_rate": 0.0,
"cost_per_view": 0,
"intervals": [],
"creatives": []
},
{
"name": "Geofence Campaign (Demo)",
"global_master_campaign_id": "TEST_1932625",
"organization": "reachlocal",
"start_date": "2020-11-01",
"end_date": null,
"type": "display",
"status": "running",
"spend": 50.0,
"impressions": 2784.0,
"clicks": 27.0,
"form_submissions_ct": 0.0,
"form_submissions_vt": 0.0,
"priority_page_views_ct": 0.0,
"priority_page_views_vt": 0.0,
"website_visits_vt": 0.0,
"walk_ins": 0.0,
"ctr": 0.97,
"cpm": 17.96,
"cpc": 1.85,
"cost_per_submission": 0,
"div": 0.0,
"cpdiv": 0,
"video_full_screen": 0.0,
"video_mute": 0.0,
"video_unmute": 0.0,
"video_pause": 0.0,
"video_resume": 0.0,
"video_views": 0.0,
"total_conversions": 0.0,
"click_through_conversions": 0.0,
"view_through_conversions": 0.0,
"video_played_to_25_pct": 0.0,
"video_played_to_50_pct": 0.0,
"video_played_to_75_pct": 0.0,
"completed_views": 0.0,
"video_complete_rate": 0.0,
"view_thru_rate": 0.0,
"cost_per_view": 0,
"intervals": [],
"creatives": []
},
{
"name": "Youtube Campaign (Demo)",
"global_master_campaign_id": "TEST_1932638",
"organization": "reachlocal",
"start_date": "2020-11-01",
"end_date": null,
"type": "youtube",
"status": "running",
"spend": 50.0,
"impressions": 2928.0,
"clicks": 37.0,
"form_submissions_ct": 0.0,
"form_submissions_vt": 0.0,
"priority_page_views_ct": 0.0,
"priority_page_views_vt": 0.0,
"website_visits_vt": 0.0,
"walk_ins": 0.0,
"ctr": 1.26,
"cpm": 17.08,
"cpc": 1.35,
"cost_per_submission": 0,
"div": 0.0,
"cpdiv": 0,
"video_full_screen": 0.0,
"video_mute": 0.0,
"video_unmute": 0.0,
"video_pause": 0.0,
"video_resume": 0.0,
"video_views": 0.0,
"total_conversions": 0.0,
"click_through_conversions": 0.0,
"view_through_conversions": 0.0,
"video_played_to_25_pct": 0.0,
"video_played_to_50_pct": 0.0,
"video_played_to_75_pct": 0.0,
"completed_views": 0.0,
"video_complete_rate": 0.0,
"view_thru_rate": 0.0,
"cost_per_view": 0,
"intervals": [],
"creatives": []
}
],
"line_items": [
{
"name": "Line Item (Demo) 1",
"line_item_id": 1,
"organization": "gannett",
"impressions": 830.0,
"clicks": 14.0,
"total_active_time_view": 335.83,
"ctr": 1.69,
"video_full_screen": 16.0,
"video_mute": 8.0,
"video_unmute": 12.0,
"video_pause": 8.0,
"video_resume": 12.0,
"video_views": 26.0,
"total_conversions": 36.0,
"click_through_conversions": 10.0,
"view_through_conversions": 26.0,
"video_played_to_25_pct": 8.0,
"video_played_to_50_pct": 12.0,
"video_played_to_75_pct": 16.0,
"completed_views": 20.0,
"video_complete_rate": 76.92,
"view_thru_rate": 2.41,
"intervals": [
{
"start_date": "2020-12-12",
"impressions": 444.0,
"clicks": 10.0,
"total_active_time_view": 59.2,
"ctr": 2.25,
"video_full_screen": 8.0,
"video_mute": 4.0,
"video_unmute": 6.0,
"video_pause": 4.0,
"video_resume": 6.0,
"video_views": 13.0,
"total_conversions": 16.0,
"click_through_conversions": 8.0,
"view_through_conversions": 8.0,
"video_played_to_25_pct": 4.0,
"video_played_to_50_pct": 6.0,
"video_played_to_75_pct": 8.0,
"completed_views": 10.0,
"video_complete_rate": 76.92,
"view_thru_rate": 2.25
},
{
"start_date": "2020-12-13",
"impressions": 386.0,
"clicks": 4.0,
"total_active_time_view": 276.63,
"ctr": 1.04,
"video_full_screen": 8.0,
"video_mute": 4.0,
"video_unmute": 6.0,
"video_pause": 4.0,
"video_resume": 6.0,
"video_views": 13.0,
"total_conversions": 20.0,
"click_through_conversions": 2.0,
"view_through_conversions": 18.0,
"video_played_to_25_pct": 4.0,
"video_played_to_50_pct": 6.0,
"video_played_to_75_pct": 8.0,
"completed_views": 10.0,
"video_complete_rate": 76.92,
"view_thru_rate": 2.59
}
],
"creatives": [
{
"creative_id": 1,
"publisher_id": 2117,
"publisher_name": "DoubleClick",
"name": "Creative (Demo) 1",
"impressions": 564.0,
"clicks": 8.0,
"total_active_time_view": 221.03,
"ctr": 1.42,
"video_full_screen": 8.0,
"video_mute": 4.0,
"video_unmute": 6.0,
"video_pause": 4.0,
"video_resume": 6.0,
"video_views": 14.0,
"total_conversions": 18.0,
"click_through_conversions": 5.0,
"view_through_conversions": 13.0,
"video_played_to_25_pct": 4.0,
"video_played_to_50_pct": 6.0,
"video_played_to_75_pct": 8.0,
"completed_views": 10.0,
"video_complete_rate": 71.43,
"view_thru_rate": 1.77,
"intervals": [
{
"start_date": "2020-12-12",
"impressions": 314.0,
"clicks": 6.0,
"total_active_time_view": 41.87,
"ctr": 1.91,
"video_full_screen": 4.0,
"video_mute": 2.0,
"video_unmute": 3.0,
"video_pause": 2.0,
"video_resume": 3.0,
"video_views": 8.0,
"total_conversions": 8.0,
"click_through_conversions": 4.0,
"view_through_conversions": 4.0,
"video_played_to_25_pct": 2.0,
"video_played_to_50_pct": 3.0,
"video_played_to_75_pct": 4.0,
"completed_views": 5.0,
"video_complete_rate": 62.5,
"view_thru_rate": 1.59
},
{
"start_date": "2020-12-13",
"impressions": 250.0,
"clicks": 2.0,
"total_active_time_view": 179.17,
"ctr": 0.8,
"video_full_screen": 4.0,
"video_mute": 2.0,
"video_unmute": 3.0,
"video_pause": 2.0,
"video_resume": 3.0,
"video_views": 6.0,
"total_conversions": 10.0,
"click_through_conversions": 1.0,
"view_through_conversions": 9.0,
"video_played_to_25_pct": 2.0,
"video_played_to_50_pct": 3.0,
"video_played_to_75_pct": 4.0,
"completed_views": 5.0,
"video_complete_rate": 83.33,
"view_thru_rate": 2.0
}
]
},
{
"creative_id": 2,
"publisher_id": 2117,
"publisher_name": "DoubleClick",
"name": "Creative (Demo) 2",
"impressions": 266.0,
"clicks": 6.0,
"total_active_time_view": 114.8,
"ctr": 2.26,
"video_full_screen": 8.0,
"video_mute": 4.0,
"video_unmute": 6.0,
"video_pause": 4.0,
"video_resume": 6.0,
"video_views": 12.0,
"total_conversions": 18.0,
"click_through_conversions": 5.0,
"view_through_conversions": 13.0,
"video_played_to_25_pct": 4.0,
"video_played_to_50_pct": 6.0,
"video_played_to_75_pct": 8.0,
"completed_views": 10.0,
"video_complete_rate": 83.33,
"view_thru_rate": 3.76,
"intervals": [
{
"start_date": "2020-12-12",
"impressions": 130.0,
"clicks": 4.0,
"total_active_time_view": 17.33,
"ctr": 3.08,
"video_full_screen": 4.0,
"video_mute": 2.0,
"video_unmute": 3.0,
"video_pause": 2.0,
"video_resume": 3.0,
"video_views": 5.0,
"total_conversions": 8.0,
"click_through_conversions": 4.0,
"view_through_conversions": 4.0,
"video_played_to_25_pct": 2.0,
"video_played_to_50_pct": 3.0,
"video_played_to_75_pct": 4.0,
"completed_views": 5.0,
"video_complete_rate": 100.0,
"view_thru_rate": 3.85
},
{
"start_date": "2020-12-13",
"impressions": 136.0,
"clicks": 2.0,
"total_active_time_view": 97.47,
"ctr": 1.47,
"video_full_screen": 4.0,
"video_mute": 2.0,
"video_unmute": 3.0,
"video_pause": 2.0,
"video_resume": 3.0,
"video_views": 7.0,
"total_conversions": 10.0,
"click_through_conversions": 1.0,
"view_through_conversions": 9.0,
"video_played_to_25_pct": 2.0,
"video_played_to_50_pct": 3.0,
"video_played_to_75_pct": 4.0,
"completed_views": 5.0,
"video_complete_rate": 71.43,
"view_thru_rate": 3.68
}
]
}
]
},
{
"name": "Line Item (Demo) 2",
"line_item_id": 2,
"organization": "gannett",
"impressions": 1647.0,
"clicks": 20.0,
"total_active_time_view": 653.02,
"ctr": 1.21,
"video_full_screen": 16.0,
"video_mute": 8.0,
"video_unmute": 12.0,
"video_pause": 8.0,
"video_resume": 12.0,
"video_views": 34.0,
"total_conversions": 36.0,
"click_through_conversions": 10.0,
"view_through_conversions": 26.0,
"video_played_to_25_pct": 8.0,
"video_played_to_50_pct": 12.0,
"video_played_to_75_pct": 16.0,
"completed_views": 20.0,
"video_complete_rate": 58.82,
"view_thru_rate": 1.21,
"intervals": [
{
"start_date": "2020-12-12",
"impressions": 904.0,
"clicks": 10.0,
"total_active_time_view": 120.53,
"ctr": 1.11,
"video_full_screen": 8.0,
"video_mute": 4.0,
"video_unmute": 6.0,
"video_pause": 4.0,
"video_resume": 6.0,
"video_views": 15.0,
"total_conversions": 16.0,
"click_through_conversions": 8.0,
"view_through_conversions": 8.0,
"video_played_to_25_pct": 4.0,
"video_played_to_50_pct": 6.0,
"video_played_to_75_pct": 8.0,
"completed_views": 10.0,
"video_complete_rate": 66.67,
"view_thru_rate": 1.11
},
{
"start_date": "2020-12-13",
"impressions": 743.0,
"clicks": 10.0,
"total_active_time_view": 532.48,
"ctr": 1.35,
"video_full_screen": 8.0,
"video_mute": 4.0,
"video_unmute": 6.0,
"video_pause": 4.0,
"video_resume": 6.0,
"video_views": 19.0,
"total_conversions": 20.0,
"click_through_conversions": 2.0,
"view_through_conversions": 18.0,
"video_played_to_25_pct": 4.0,
"video_played_to_50_pct": 6.0,
"video_played_to_75_pct": 8.0,
"completed_views": 10.0,
"video_complete_rate": 52.63,
"view_thru_rate": 1.35
}
],
"creatives": [
{
"creative_id": 1,
"publisher_id": 2117,
"publisher_name": "DoubleClick",
"name": "Creative (Demo) 1",
"impressions": 425.0,
"clicks": 7.0,
"total_active_time_view": 231.67,
"ctr": 1.65,
"video_full_screen": 8.0,
"video_mute": 4.0,
"video_unmute": 6.0,
"video_pause": 4.0,
"video_resume": 6.0,
"video_views": 14.0,
"total_conversions": 18.0,
"click_through_conversions": 5.0,
"view_through_conversions": 13.0,
"video_played_to_25_pct": 4.0,
"video_played_to_50_pct": 6.0,
"video_played_to_75_pct": 8.0,
"completed_views": 10.0,
"video_complete_rate": 71.43,
"view_thru_rate": 2.35,
"intervals": [
{
"start_date": "2020-12-12",
"impressions": 125.0,
"clicks": 5.0,
"total_active_time_view": 16.67,
"ctr": 4.0,
"video_full_screen": 4.0,
"video_mute": 2.0,
"video_unmute": 3.0,
"video_pause": 2.0,
"video_resume": 3.0,
"video_views": 5.0,
"total_conversions": 8.0,
"click_through_conversions": 4.0,
"view_through_conversions": 4.0,
"video_played_to_25_pct": 2.0,
"video_played_to_50_pct": 3.0,
"video_played_to_75_pct": 4.0,
"completed_views": 5.0,
"video_complete_rate": 100.0,
"view_thru_rate": 4.0
},
{
"start_date": "2020-12-13",
"impressions": 300.0,
"clicks": 2.0,
"total_active_time_view": 215.0,
"ctr": 0.67,
"video_full_screen": 4.0,
"video_mute": 2.0,
"video_unmute": 3.0,
"video_pause": 2.0,
"video_resume": 3.0,
"video_views": 9.0,
"total_conversions": 10.0,
"click_through_conversions": 1.0,
"view_through_conversions": 9.0,
"video_played_to_25_pct": 2.0,
"video_played_to_50_pct": 3.0,
"video_played_to_75_pct": 4.0,
"completed_views": 5.0,
"video_complete_rate": 55.56,
"view_thru_rate": 1.67
}
]
},
{
"creative_id": 2,
"publisher_id": 2117,
"publisher_name": "DoubleClick",
"name": "Creative (Demo) 2",
"impressions": 1222.0,
"clicks": 13.0,
"total_active_time_view": 421.35,
"ctr": 1.06,
"video_full_screen": 8.0,
"video_mute": 4.0,
"video_unmute": 6.0,
"video_pause": 4.0,
"video_resume": 6.0,
"video_views": 20.0,
"total_conversions": 18.0,
"click_through_conversions": 5.0,
"view_through_conversions": 13.0,
"video_played_to_25_pct": 4.0,
"video_played_to_50_pct": 6.0,
"video_played_to_75_pct": 8.0,
"completed_views": 10.0,
"video_complete_rate": 50.0,
"view_thru_rate": 0.82,
"intervals": [
{
"start_date": "2020-12-12",
"impressions": 779.0,
"clicks": 5.0,
"total_active_time_view": 103.87,
"ctr": 0.64,
"video_full_screen": 4.0,
"video_mute": 2.0,
"video_unmute": 3.0,
"video_pause": 2.0,
"video_resume": 3.0,
"video_views": 10.0,
"total_conversions": 8.0,
"click_through_conversions": 4.0,
"view_through_conversions": 4.0,
"video_played_to_25_pct": 2.0,
"video_played_to_50_pct": 3.0,
"video_played_to_75_pct": 4.0,
"completed_views": 5.0,
"video_complete_rate": 50.0,
"view_thru_rate": 0.64
},
{
"start_date": "2020-12-13",
"impressions": 443.0,
"clicks": 8.0,
"total_active_time_view": 317.48,
"ctr": 1.81,
"video_full_screen": 4.0,
"video_mute": 2.0,
"video_unmute": 3.0,
"video_pause": 2.0,
"video_resume": 3.0,
"video_views": 10.0,
"total_conversions": 10.0,
"click_through_conversions": 1.0,
"view_through_conversions": 9.0,
"video_played_to_25_pct": 2.0,
"video_played_to_50_pct": 3.0,
"video_played_to_75_pct": 4.0,
"completed_views": 5.0,
"video_complete_rate": 50.0,
"view_thru_rate": 1.13
}
]
}
]
}
]
}
}
| Field Name | Datatype | Description |
|---|---|---|
| api_name | String | Name of the API |
| api_run_date | String | Date report was run |
| earliest_date_available | String | How far back data is available |
| start_date | String | Start Date |
| end_date | String | End Date |
| time_zone | String | Time Zone of Data |
| interval_size | String | Interval Size (none, day, calendar_week, or calendar_month) |
| currency | String | Currency for Advertiser |
| global_master_advertiser_id | String | Identifier for Advertiser |
| advertiser_name | String | Name of Advertiser |
| report_data | Object | Report Data Object (with Line Items) or Report Data Object (with Campaigns) |
Report Data Object (with Line Items)
| Field Name | Datatype | Description |
|---|---|---|
| totals | Object | Object of totals details. Totals Object |
| intervals | Object | Object of intervals details. Intervals Object |
| campaigns | Object | Object of campaigns details. Campaigns Object |
| line_items | Object | Object of line items details. Line Items Object |
Report Data Object (with Campaigns)
| Field Name | Datatype | Description |
|---|---|---|
| totals | Object | Object of totals details. Totals Object |
| campaigns | Object | Object of campaigns details. Campaigns Object |
| line_items | Object | Object of line items details. Line Items Object |
| Field Name | Datatype | Description |
|---|---|---|
| clicks | Integer | Total clicks |
| impressions | Integer | Total impressions |
| ctr | Float | Overall Click-through Rate |
| video_full_screen | Float | Number of Full-Screen Video Views The field is nullable |
| video_mute | Float | Number of Muted Video Views The field is nullable |
| video_unmute | Float | Number of Unmuted Video Views The field is nullable |
| video_pause | Float | Number of Paused Video Views The field is nullable |
| video_resume | Float | Number of Resumed Video Views The field is nullable |
| video_views | Float | Number of Video Views The field is nullable |
| total_conversions | Float | Number of Conversions The field is nullable |
| click_through_conversions | Float | Number of Click-Through Conversions The field is nullable |
| view_through_conversions | Float | Number of View-Through Conversions The field is nullable |
| video_played_to_25_pct | Float | Number of Video Views Played to 25 percent The field is nullable |
| video_played_to_50_pct | Float | Number of Video Views Played to 50 percent The field is nullable |
| video_played_to_75_pct | Float | Number of Video Views Played to 75 percent The field is nullable |
| completed_views | Float | Number of Completed Views The field is nullable |
| video_complete_rate | Float | Rate of Video Completion vs Partial Views The field is nullable |
| view_thru_rate | Float | View-Through Rate The field is nullable |
| Field Name | Datatype | Description |
|---|---|---|
| start_date | String | Start Date of interval |
| clicks | Integer | Number of clicks for interval |
| impressions | Integer | Number of impressions for interval |
| ctr | Float | Click-through Rate for interval |
| video_full_screen | Float | Number of Full-Screen Video Views |
| video_mute | Float | Number of Muted Video Views The field is nullable |
| video_unmute | Float | Number of Unmuted Video Views The field is nullable |
| video_pause | Float | Number of Paused Video Views The field is nullable |
| video_resume | Float | Number of Resumed Video Views The field is nullable |
| video_views | Float | Number of Video Views The field is nullable |
| total_conversions | Float | Number of Conversions The field is nullable |
| click_through_conversions | Float | Number of Click-Through Conversions The field is nullable |
| view_through_conversions | Float | Number of View-Through Conversions The field is nullable |
| video_played_to_25_pct | Float | Number of Video Views Played to 25 percent The field is nullable |
| video_played_to_50_pct | Float | Number of Video Views Played to 50 percent The field is nullable |
| video_played_to_75_pct | Float | Number of Video Views Played to 75 percent The field is nullable |
| completed_views | Float | Number of Completed Views The field is nullable |
| video_complete_rate | Float | Rate of Video Completion vs Partial Views The field is nullable |
| view_thru_rate | Float | View-Through Rate The field is nullable |
| Field Name | Datatype | Description |
|---|---|---|
| name | String | Campaign Name |
| global_master_campaign_id | String | Unique Identifier for Campaign |
| organization | String | Either reachlocal or gannett |
| start_date | String | Campaign Start Date |
| end_date | String | Campaign End Date The field is nullable |
| type | String | Type of Campaign |
| status | String | Status of Campaign |
| spend | Float | Total Spend for Campaign |
| impressions | Float | Total Impressions for Campaign |
| clicks | Float | Total Clicks for Campaign |
| ctr | Float | Overall Click-through Rate of Campaign |
| cpm | Float | Overall Click Per Thousand Impressions for Campaign |
| cpc | Float | Cost Per Click for Campaign |
| walk_ins | Float | Total Walk-ins for Campaign |
| cost_per_view | Float | Total Cost Per View for Campaign |
| form_submissions_ct | Float | Total For Submission Click Through for Campaign |
| form_submissions_vt | Float | Total Form Submission View Through for Campaign |
| website_visits_vt | Float | Total Website Visits View Through for Campaign |
| cost_per_submission | Float | Total Cost Per Submission for Campaign |
| priority_page_views_ct | Float | Total Priority Page View Click Through for Campaign |
| priority_page_views_vt | Float | Total Priority Page View Through for Campaign |
| video_full_screen | Float | Number of Full-Screen Video Views The field is nullable |
| video_mute | Float | Number of Muted Video Views The field is nullable |
| video_unmute | Float | Number of Unmuted Video Views The field is nullable |
| video_pause | Float | Number of Paused Video Views The field is nullable |
| video_resume | Float | Number of Resumed Video Views The field is nullable |
| video_views | Float | Number of Video Views |
| total_conversions | Float | Number of Conversions The field is nullable |
| click_through_conversions | Float | Number of Click-Through Conversions The field is nullable |
| view_through_conversions | Float | Number of View-Through Conversions The field is nullable |
| video_played_to_25_pct | Float | Number of Video Views Played to 25 percent The field is nullable |
| video_played_to_50_pct | Float | Number of Video Views Played to 50 percent The field is nullable |
| video_played_to_75_pct | Float | Number of Video Views Played to 75 percent The field is nullable |
| completed_views | Float | Total Completed Views for Campaign |
| video_complete_rate | Float | Total Video Completion Rate |
| view_thru_rate | Float | Total View-Through Rate |
| cost_per_view | Float | Cost per View |
| div | Float | Display-Influenced Visits |
| cpdiv | Float | Cost per Display-Influenced Visit |
| creatives | Object | Object of creatives details. Campaign Creatives Object |
| Field Name | Datatype | Description |
|---|---|---|
| name | String | Name of Line Item |
| line_item_id | Int | Identifier of Line Item |
| organization | String | Either reachlocal or gannett |
| impressions | Int | Total Impressions for Line Item |
| clicks | Int | Total Clicks for Line Item |
| total_active_time_view | Float | Total Time (minutes) the ad was viewed by a consumers |
| ctr | Float | Overall Click-through Rate of Line Item |
| universal_interaction_rate | Float | Overall Universal Interaction Rate for Line Item (This MOAT metric was deprecated on 12-31-2019) |
| universal_interaction_time | Float | Overall Universal Interaction Time for Line Item (This MOAT metric was deprecated on 12-31-2019) |
| hover_rate | Float | Hover Rate for Line Item (This MOAT metric was deprecated on 12-31-2019) |
| attention_quality | Float | Attention Quality for Line Item (This MOAT metric was deprecated on 12-31-2019) |
| intervals | Object | Object of line items intervals. Line Item Intervals Object |
| creatives | Object | Object of line items creatives. Line Item Creatives Object |
| Field Name | Datatype | Description |
|---|---|---|
| start_date | String | == |
| impressions | Integer | Total Impressions for Interval |
| clicks | Integer | Total Clicks for Interval |
| total_active_time_view | Float | Total Time (minutes) the ad was viewed by a consumers |
| ctr | Float | Overall Click-through Rate of Interval |
| universal_interaction_rate | Float | Overall Universal Interaction Rate for Interval (This MOAT metric was deprecated on 12-31-2019) |
| universal_interaction_time | Float | Overall Universal Interaction Time for Interval (This MOAT metric was deprecated on 12-31-2019) |
| hover_rate | Float | Hover Rate for Interval (This MOAT metric was deprecated on 12-31-2019) |
| attention_quality | Float | Attention Quality for Interval (This MOAT metric was deprecated on 12-31-2019) |
| video_full_screen | Float | Number of Full-Screen Video Views The field is nullable |
| video_mute | Float | Number of Muted Video Views The field is nullable |
| video_unmute | Float | Number of Unmuted Video Views The field is nullable |
| video_pause | Float | Number of Paused Video Views The field is nullable |
| video_resume | Float | Number of Resumed Video Views The field is nullable |
| video_views | Float | Number of Video Views The field is nullable |
| total_conversions | Float | Number of Conversions The field is nullable |
| click_through_conversions | Float | Number of Click-Through Conversions The field is nullable |
| view_through_conversions | Float | Number of View-Through Conversions The field is nullable |
| video_played_to_25_pct | Float | Number of Video Views Played to 25 percent The field is nullable |
| video_played_to_50_pct | Float | Number of Video Views Played to 50 percent The field is nullable |
| video_played_to_75_pct | Float | Number of Video Views Played to 75 percent The field is nullable |
| completed_views | Float | Number of Completed Views The field is nullable |
| video_complete_rate | Float | Rate of Video Completion vs Partial Views The field is nullable |
| view_thru_rate | Float | View-Through Rate The field is nullable |
| cost_per_view | Float | Cost per View |
| Field Name | Datatype | Description |
|---|---|---|
| creative_id | String | Identifier for Creative |
| publisher_id | String | Identifier for Publisher |
| publisher_name | String | Name of Publisher |
| name | String | Name of Creative |
| creative_size | String | Size of Creative |
| preview_url | String | Preview URL for creative |
| impressions | Integer | Total Impressions for Creative |
| clicks | Integer | Total Clicks for Creative |
| total_active_time_view | Float | Total Time (minutes) the ad was viewed by a consumers |
| ctr | Float | Overall Click-through Rate of Creative |
| universal_interaction_rate | Float | Overall Universal Interaction Rate for Creative (This MOAT metric was deprecated on 12-31-2019) |
| universal_interaction_time | Float | Overall Universal Interaction Time for Creative (This MOAT metric was deprecated on 12-31-2019) |
| hover_rate | Float | Hover Rate for Creative (This MOAT metric was deprecated on 12-31-2019) |
| attention_quality | Float | Attention Quality for Creative (This MOAT metric was deprecated on 12-31-2019) |
| video_full_screen | Float | Number of Full-Screen Video Views The field is nullable |
| video_mute | Float | Number of Muted Video Views The field is nullable |
| video_unmute | Float | Number of Unmuted Video Views The field is nullable |
| video_pause | Float | Number of Paused Video Views The field is nullable |
| video_resume | Float | Number of Resumed Video Views The field is nullable |
| video_views | Float | Number of Video Views The field is nullable |
| total_conversions | Float | Number of Conversions The field is nullable |
| click_through_conversions | Float | Number of Click-Through Conversions The field is nullable |
| view_through_conversions | Float | Number of View-Through Conversions The field is nullable |
| video_played_to_25_pct | Float | Number of Video Views Played to 25 percent The field is nullable |
| video_played_to_50_pct | Float | Number of Video Views Played to 50 percent The field is nullable |
| video_played_to_75_pct | Float | Number of Video Views Played to 75 percent The field is nullable |
| completed_views | Float | Number of Completed Views The field is nullable |
| video_complete_rate | Float | Rate of Video Completion vs Partial Views The field is nullable |
| view_thru_rate | Float | View-Through Rate The field is nullable |
| cost_per_view | Float | Cost per View |
| intervals | Object | Object of line items creatives intervals. Line Items Creatives Intervals Object |
| Field Name | Datatype | Description |
|---|---|---|
| creative_id | Integer | Identifier for Creative |
| publisher_id | Integer | Identifier for Publisher |
| publisher_name | String | Name of Publisher |
| creative_name | String | Name of Creative The field is nullable |
| creative_type | String | Type of Creative |
| creative_template_id | Integer | The template id of the creative (Used for paramount creatives) |
| native_style_id | Integer | The native style id of the creative (Used for paramount creatives) |
| creative_size | String | Size of Creative |
| preview_url | String | Preview URL for creative |
| spend | Float | Total Spend for Campaign |
| impressions | Float | Total Impressions for Interval |
| clicks | Float | Total Clicks for Interval |
| total_active_time_view | Float | Total Time (minutes) the ad was viewed by a consumers |
| ctr | Float | Overall Click-through Rate of Interval |
| cpm | Float | Overall Click Per Thousand Impressions for Interval |
| cpc | Float | Cost Per Click for Interval |
| walk_ins | Float | Total Walk-ins for Interval |
| cost_per_view | Float | Total Cost Per View for Campaign |
| form_submissions_ct | Float | Total For Submission Click Through for Campaign |
| form_submissions_vt | Float | Total Form Submission View Through for Campaign |
| website_visits_vt | Float | Total Website Visits View Through for Campaign |
| cost_per_submission | Float | Total Cost Per Submission for Campaign |
| priority_page_views_ct | Float | Total Priority Page View Click Through for Campaign |
| priority_page_views_vt | Float | Total Priority Page View Through for Campaign |
| video_full_screen | Float | Number of Full-Screen Video Views The field is nullable |
| video_mute | Float | Number of Muted Video Views The field is nullable |
| video_unmute | Float | Number of Unmuted Video Views The field is nullable |
| video_pause | Float | Number of Paused Video Views The field is nullable |
| video_resume | Float | Number of Resumed Video Views The field is nullable |
| video_views | Float | Number of Video Views |
| total_conversions | Float | Number of Conversions The field is nullable |
| click_through_conversions | Float | Number of Click-Through Conversions The field is nullable |
| view_through_conversions | Float | Number of View-Through Conversions The field is nullable |
| video_played_to_25_pct | Float | Number of Video Views Played to 25 percent The field is nullable |
| video_played_to_50_pct | Float | Number of Video Views Played to 50 percent The field is nullable |
| video_played_to_75_pct | Float | Number of Video Views Played to 75 percent The field is nullable |
| completed_views | Float | Total Completed Views for Campaign |
| video_complete_rate | Float | Total Video Completion Rate |
| view_thru_rate | Float | Total View-Through Rate |
| cost_per_view | Float | Cost per View |
| div | Float | Display-Influenced Visits |
| cpdiv | Float | Cost per Display-Influenced Visit |
Line Items Creatives Intervals Object
| Field Name | Datatype | Description |
|---|---|---|
| start_date | String | Start Date of Interval |
| impressions | Integer | Total Impressions for Interval |
| clicks | Integer | Total Clicks for Interval |
| total_active_time_view | Float | Total Time (minutes) the ad was viewed by a consumers |
| ctr | Float | Overall Click-through Rate of Interval |
| universal_interaction_rate | Float | Overall Universal Interaction Rate for Interval (This MOAT metric was deprecated on 12-31-2019) |
| universal_interaction_time | Float | Overall Universal Interaction Time for Interval (This MOAT metric was deprecated on 12-31-2019) |
| hover_rate | Float | Hover Rate for Interval (This MOAT metric was deprecated on 12-31-2019) |
| attention_quality | Float | Attention Quality for Interval (This MOAT metric was deprecated on 12-31-2019) |
| video_full_screen | Float | Number of Full-Screen Video Views The field is nullable |
| video_mute | Float | Number of Muted Video Views The field is nullable |
| video_unmute | Float | Number of Unmuted Video Views The field is nullable |
| video_pause | Float | Number of Paused Video Views The field is nullable |
| video_resume | Float | Number of Resumed Video Views The field is nullable |
| video_views | Float | Number of Video Views The field is nullable |
| total_conversions | Float | Number of Conversions The field is nullable |
| click_through_conversions | Float | Number of Click-Through Conversions The field is nullable |
| view_through_conversions | Float | Number of View-Through Conversions The field is nullable |
| video_played_to_25_pct | Float | Number of Video Views Played to 25 percent The field is nullable |
| video_played_to_50_pct | Float | Number of Video Views Played to 50 percent The field is nullable |
| video_played_to_75_pct | Float | Number of Video Views Played to 75 percent The field is nullable |
| completed_views | Floates | Number of Completed Views The field is nullable |
| video_complete_rate | Float | Rate of Video Completion vs Partial Views The field is nullable |
| view_thru_rate | Float | View-Through Rate The field is nullable |
| cost_per_view | Float | Cost per View |
GeoFence Campaign Metrics
Resource Overview
| Method | URI Format |
|---|---|
| GET | /client_reports/geofence_summary/[gmaid]?[query_params] |
Use GET to retrieve information for the GeoFence Summary Report for a given advertiser.
The data returned will include impressions, walk_ins, ctr, clicks, cpc, cpw, cpm, and spend organized by campaign and broken down by geofence and conversion_fence.
Parameters
When using the GET method, the results can be filtered using these parameters:
| Param | Function |
|---|---|
| start_date | Restricts the results to those occurring on or after this date |
| end_date | Restricts the results to those occurring on or before this date |
| global_master_campaign_id[] | Restrict results to one or more specific campaigns. This should be a comma separated string. Ex: global_master_campaign_id[]=TEST_1,TEST_2 |
| campaign_status[] | Restrict results to all campaigns with given status values. Allowed values are running, stopped and ended. This should be a comma separated string. Ex: campaign_status[]=running,stopped |
| interval_size | Use calendar_month or calendar_week to roll up the data points into calendar intervals (default is 1 day per interval) |
| geofence[] | Restrict results to the given geofence ids. Geofence ids can be found in the available_geofences section. This should be a comma separated string. Ex: geofence[]=1,2 |
| conversion_fence[] | Restrict results to the given conversion fence ids. Conversion Fence ids can be found in the available_conversion_fences section. This should be a comma separated string. Ex: conversion_fence[]=1,2 |
Note: Maximum date range for this API is 31 days.
Response Data Details:
Retrieve data for a specific range of datesß
curl -H "Authorization: Bearer OAUTH_ACCESS_TOKEN" \
https://api.localiqservices.com/client_reports/geofence_summary/TEST_1?start_date=2016-12-01&end_date=2016-12-31
Retrieve data for a specific campaign starting on a certain date
curl -g -H "Authorization: Bearer OAUTH_ACCESS_TOKEN \
https://api.localiqservices.com/client_reports/geofence_summary/TEST_1?global_master_campaign_id[]=TEST_1&start_date=2016-10-01&end_date=2016-12-31
Retrieve data for campaigns that are stopped and running
curl -g -H "Authorization: Bearer OAUTH_ACCESS_TOKEN" \
https://api.localiqservices.com/client_reports/geofence_summary/TEST_1?&campaign_status[]=running,stopped&start_date=2016-10-01&end_date=2016-12-31
Retrieve data for specific geofences and conversion_fences
curl -g -H "Authorization: Bearer OAUTH_ACCESS_TOKEN" \
https://api.localiqservices.com/client_reports/geofence_summary/TEST_1?&goefence[]=1,2&conversion_fence[]=1,2&start_date=2016-10-01&end_date=2016-12-31
Example Response
{
"report_type": "geofence_summary",
"report_date": "2020-10-15",
"earliest_date_available": "2020-01-01",
"start_date": "2020-10-10",
"end_date": "2020-10-10",
"time_zone": "America/Los_Angeles",
"interval_size": "day",
"currency": "USD",
"global_master_advertiser_id": "TEST_1",
"report_data": {
"campaigns": [
{
"name": "Geofence Campaign (Demo)",
"global_master_campaign_id": "TEST_1368571",
"start_date": "2020-01-01",
"end_date": null,
"type": "display",
"intervals": [
{
"start_date": "2020-10-10",
"impressions": 1136,
"walk_ins": 17,
"ctr": 0.88,
"clicks": 10,
"cpc": 2.5,
"cpw": 1.47,
"cpm": 22.01,
"spend": 25,
"geofences": [
{
"impressions": 522,
"walk_ins": 10,
"ctr": 0.57,
"clicks": 3,
"cpc": 2.1,
"cpw": 0.63,
"cpm": 12.06,
"spend": 6.29,
"name": "Geofence (Demo) 1",
"geofence_id": 1,
"conversion_fences": [
{
"name": "Conversion Fense (Demo) 1",
"conversion_fence_id": 1,
"walk_ins": 6,
"cpw": 0.13,
"spend": 0.79
},
{
"name": "Conversion Fense (Demo) 2",
"conversion_fence_id": 2,
"walk_ins": 4,
"cpw": 1.38,
"spend": 5.51
}
]
},
{
"impressions": 614,
"walk_ins": 7,
"ctr": 1.14,
"clicks": 7,
"cpc": 2.67,
"cpw": 2.67,
"cpm": 30.47,
"spend": 18.71,
"name": "Geofence (Demo) 2",
"geofence_id": 2,
"conversion_fences": [
{
"name": "Conversion Fense (Demo) 1",
"conversion_fence_id": 1,
"walk_ins": 4,
"cpw": 1.53,
"spend": 6.11
},
{
"name": "Conversion Fense (Demo) 2",
"conversion_fence_id": 2,
"walk_ins": 3,
"cpw": 4.2,
"spend": 12.6
}
]
}
],
"conversion_fences": [
{
"name": "Conversion Fense (Demo) 1",
"conversion_fence_id": 1,
"walk_ins": 10,
"geofences": [
{
"name": "Geofence (Demo) 1",
"geofence_id": 1,
"walk_ins": 6,
"cpw": 0.13
},
{
"name": "Geofence (Demo) 2",
"geofence_id": 2,
"walk_ins": 4,
"cpw": 1.53
}
],
"cpw": 0.69
},
{
"name": "Conversion Fense (Demo) 2",
"conversion_fence_id": 2,
"walk_ins": 7,
"geofences": [
{
"name": "Geofence (Demo) 1",
"geofence_id": 1,
"walk_ins": 4,
"cpw": 1.38
},
{
"name": "Geofence (Demo) 2",
"geofence_id": 2,
"walk_ins": 3,
"cpw": 4.2
}
],
"cpw": 2.59
}
]
}
]
},
{
"name": "Xmedia Campaign (Demo)",
"global_master_campaign_id": "TEST_1368577",
"start_date": "2020-01-01",
"end_date": null,
"type": "xmedia",
"intervals": [
{
"start_date": "2020-10-10",
"impressions": 200,
"walk_ins": 30,
"ctr": 1,
"clicks": 2,
"cpc": 2.08,
"cpw": 0.14,
"cpm": 20.83,
"spend": 4.17,
"geofences": [
{
"impressions": 30,
"walk_ins": 11,
"ctr": 0,
"clicks": 0,
"cpc": 0,
"cpw": 0.11,
"cpm": 41.74,
"spend": 1.25,
"name": "Geofence (Demo) 1",
"geofence_id": 1,
"conversion_fences": [
{
"name": "Conversion Fense (Demo) 1",
"conversion_fence_id": 1,
"walk_ins": 5,
"cpw": 0.01,
"spend": 0.07
},
{
"name": "Conversion Fense (Demo) 2",
"conversion_fence_id": 2,
"walk_ins": 6,
"cpw": 0.2,
"spend": 1.18
}
]
},
{
"impressions": 170,
"walk_ins": 19,
"ctr": 1.18,
"clicks": 2,
"cpc": 1.46,
"cpw": 0.15,
"cpm": 17.14,
"spend": 2.91,
"name": "Geofence (Demo) 2",
"geofence_id": 2,
"conversion_fences": [
{
"name": "Conversion Fense (Demo) 1",
"conversion_fence_id": 1,
"walk_ins": 10,
"cpw": 0.08,
"spend": 0.78
},
{
"name": "Conversion Fense (Demo) 2",
"conversion_fence_id": 2,
"walk_ins": 9,
"cpw": 0.24,
"spend": 2.14
}
]
}
],
"conversion_fences": [
{
"name": "Conversion Fense (Demo) 1",
"conversion_fence_id": 1,
"walk_ins": 15,
"geofences": [
{
"name": "Geofence (Demo) 1",
"geofence_id": 1,
"walk_ins": 5,
"cpw": 0.01
},
{
"name": "Geofence (Demo) 2",
"geofence_id": 2,
"walk_ins": 10,
"cpw": 0.08
}
],
"cpw": 0.06
},
{
"name": "Conversion Fense (Demo) 2",
"conversion_fence_id": 2,
"walk_ins": 15,
"geofences": [
{
"name": "Geofence (Demo) 1",
"geofence_id": 1,
"walk_ins": 6,
"cpw": 0.2
},
{
"name": "Geofence (Demo) 2",
"geofence_id": 2,
"walk_ins": 9,
"cpw": 0.24
}
],
"cpw": 0.22
}
]
}
]
}
],
"totals_per_interval": [
{
"start_date": "2020-10-10",
"impressions": 1336,
"walk_ins": 47,
"ctr": 0.9,
"clicks": 12,
"cpc": 2.43,
"cpw": 0.62,
"cpm": 21.83,
"spend": 29.17
}
],
"totals": {
"impressions": 1336,
"walk_ins": 47,
"ctr": 0.9,
"clicks": 12,
"cpc": 2.43,
"cpw": 0.62,
"cpm": 21.83,
"spend": 29.17
},
"available_geofences": [
{
"geofence_id": 1,
"geofence_name": "Geofence (Demo) 1"
},
{
"geofence_id": 2,
"geofence_name": "Geofence (Demo) 2"
}
],
"available_conversion_fences": [
{
"conversion_fence_id": 1,
"conversion_fence_name": "Conversion Fense (Demo) 1"
},
{
"conversion_fence_id": 2,
"conversion_fence_name": "Conversion Fense (Demo) 2"
}
]
}
}
| Field Name | Datatype | Description |
|---|---|---|
| report_type | String | Name of the API |
| report_date | String | Date report was run |
| earliest_date_available | String | Earliest Data is Available |
| start_date | String | Start date of report |
| end_date | String | End date of report |
| time_zone | String | Time Zone |
| interval_size | String | Interval Size ('none', 'day', 'calendar_week' or 'calendar_month') |
| currency | String | Currency Type of Monetary Values Returned in Report (Example: USD, AUD, CAD) |
| report_data | Object | Report details |
Report Data Object
| Field Name | Datatype | Description |
|---|---|---|
| campaigns | Object | Data for specified campaign |
| totals | Object | Data for Overall Totals |
| totals_per_interval | Object | Overall Totals Broken Down by Interval |
| available_geofences | AvailableGeofence[] | Array of AvailableGeofence |
| available_conversion_fences | AvailableConversionGeofence[] | Array of AvailableConversionGeofence |
Campaigns Object
| Field Name | Datatype | Nullable | Description |
|---|---|---|---|
| name | String | No | Campaign Name |
| global_master_campaign_id | String | No | Unique Identifier for Campaign |
| start_date | String | No | Campaign Start Date |
| end_date | String | Yes | Campaign End Date |
| type | String | No | Type of Campaign |
| cycles | Cycle[] | No | Array of Cycle |
| intervals | Interval[] | No | Array of Interval |
Cycles Object
| Field Name | Datatype | Nullable | Description |
|---|---|---|---|
| campaign_cycle | String | No | Unique Identifier for Cycle |
| start_date | String | No | Cycle Start Date |
| end_date | String | Yes | Cycle End Date |
| intervals | Interval[] | No | Array of Interval |
Intervals Object
| Field Name | Datatype | Nullable | Description |
|---|---|---|---|
| start_date | String | No | Start Date for Interval |
| impressions | Int | No | Total Impressions for Interval |
| walk_ins | Int | No | Total Walk-Ins for Interval |
| ctr | Float | No | Total Click through Rate for Interval |
| clicks | Int | No | Total Clicks for Interval |
| cpc | Float | No | Total Cost per Click for Interval |
| cpw | Float | No | Total Cost per Walk-in for Interval |
| cpm | Float | No | Total Cost per Milli for Interval |
| spend | Float | No | Total Spend for Interval |
| geofences | String | Geofence[] | Array of Geofence |
| conversion_fences | ConversionFence[] | No | Array of ConversionFence |
Geofence Object
| Field Name | Datatype | Nullable | Description |
|---|---|---|---|
| name | String | No | Geofence Name |
| geofence_id | Int | No | Geofence ID |
| impressions | Int | No | Total Impressions for Interval |
| walk_ins | Int | No | Total Walk-Ins for Interval |
| ctr | Float | No | Total Click through Rate for Interval |
| clicks | Int | No | Total Clicks for Interval |
| cpc | Float | No | Total Cost per Click for Interval |
| cpw | Float | No | Total Cost per Walk-in for Interval |
| cpm | Float | No | Total Cost per Milli for Interval |
| spend | Float | No | Total Spend for Interval |
ConversionFence Object
| Field Name | Datatype | Nullable | Description |
|---|---|---|---|
| name | String | No | Conversion Fence Name |
| conversion_fence_id | Int | No | Geofence ID |
| walk_ins | Int | No | Total Walk-Ins for Interval |
| cpw | Float | No | Total Cost per Walk-in for Interval |
| spend | Float | No | Total Spend for Interval |
Totals Object
| Field Name | Datatype | Nullable | Description |
|---|---|---|---|
| impressions | Int | No | Total Impressions for Interval |
| walk_ins | Int | No | Total Walk-Ins for Interval |
| ctr | Float | No | Total Click through Rate for Interval |
| clicks | Int | No | Total Clicks for Interval |
| cpc | Float | No | Total Cost per Click for Interval |
| cpw | Float | No | Total Cost per Walk-in for Interval |
| cpm | Float | No | Total Cost per Milli for Interval |
| spend | Float | No | Total Spend for Interval |
Totals Per Interval Object
This is an Interval object across all campaigns.
AvailableGeofence Object
| Field Name | Datatype | Nullable | Description |
|---|---|---|---|
| geofence_id | Int | No | Geofence ID |
| geofence_name | Int | No | Geofence Name |
AvailableConversionFence Object
| Field Name | Datatype | Nullable | Description |
|---|---|---|---|
| conversion_fence_id | Int | No | Conversion Fence ID |
| conversion_fence_name | Int | No | Conversion Fence Name |
Search APIs
Keyword Performance Metrics
Resource Overview
| Method | URI Format |
|---|---|
| GET | /client_reports/keyword/[gmaid]?[query_params] |
Use GET to retrieve information for the Keyword report. Data can be returned for a specific date range determined by start_date and end_date. The requirements for these parameters are described below.
The data returned will include totals for number of keywords, impressions, clicks, and click-through-rate (CTR), as well as a breakdown for each keyword. Data will be returned in pages, controlled by the parameters page and page_size. The first page is page 1. Default values of 1 and 15 will be used if not specified. Data is sorted in alphabetical order by keyword.
Note: This API will not provide an Average page position from 1/1/2020 onward in the response.
Parameters
When using the GET method, the results can be filtered using these parameters:
| Parameter | Required | Description |
|---|---|---|
| start_date | Yes | Restricts the results to those occurring on or after this date |
| end_date | Yes | Restricts the results to those occurring on or before this date |
| global_master_campaign_id[] | Restrict results to one or more specific campaigns. This should be a comma separated string. Ex: global_master_campaign_id[]=TEST_1,TEST_2 Default value: all |
|
| campaign_status[] | No | Restrict results to all campaigns with given status values. Allowed values are running, stopped and ended. This should be a comma separated string. Ex: campaign_status[]=running,stopped Default value: all |
| page_size | No | Restrict number of keywords in result Default value: 15 |
| page | No | Specifies which page of results to return Default value: 1 |
| sort_by | No | Specifies what column to sort by. Valid columns are: keyword, clicks, impressions, and ctr Default value: keyword |
| sort_dir | No | Specifies the sort direction. Can be either asc or desc Default value: asc |
| types[] | No | Specifies the campaign type of keyword. Can be search, display or xmedia. Ex: types[]=display,search,xmedia Default value: search |
Response Data Details
Retrieve data for a specific range of dates
curl -H "Authorization: Bearer OAUTH_ACCESS_TOKEN" \
https://api.localiqservices.com/client_reports/keyword/TEST_1?start_date=2016-12-01&end_date=2016-12-31&page=1&page_size=15
Retrieve data for a specific campaign starting on a certain date
curl -g -H "Authorization: Bearer OAUTH_ACCESS_TOKEN" \
https://api.localiqservices.com/client_reports/keyword/TEST_1?global_master_campaign_id[]=TEST_1&start_date=2016-10-01&end_date=2016-12-31&page=1&page_size=15
Retrieve data for campaigns that are stopped and running
curl -g -H "Authorization: Bearer OAUTH_ACCESS_TOKEN" \
https://api.localiqservices.com/client_reports/keyword/TEST_1?&campaign_status[]=running,stopped&start_date=2016-10-01&end_date=2016-12-31&page=1&page_size=15
Retrieve data for both search and display campaigns
curl -g -H "Authorization: Bearer OAUTH_ACCESS_TOKEN" \
https://api.localiqservices.com/client_reports/keyword/TEST_1?types[]=display,search&start_date=2016-10-01&end_date=2016-12-31&page=1&page_size=15
Example Response
{
"report_type": "keyword",
"report_date": "2020-10-15",
"earliest_date_available": "2020-01-01",
"start_date": "2020-10-10",
"end_date": "2020-10-10",
"time_zone": "America/Los_Angeles",
"report_data": {
"totals": {
"clicks": 17,
"impressions": 1065,
"ctr": 1.6,
"keywords": 2
},
"keywords": [
{
"keyword": "Keyword (Demo) 1 Location (Demo) 1",
"type": "search",
"clicks": 6,
"impressions": 383,
"ctr": 1.57
},
{
"keyword": "Keyword (Demo) 2 Location (Demo) 2",
"type": "search",
"clicks": 11,
"impressions": 682,
"ctr": 1.61
}
],
"unattributed_keywords": [
{
"type": "search",
"clicks": 12,
"impressions": 62,
"ctr": 19.35
}
]
},
"global_master_advertiser_id": "TEST_1",
"page": 1,
"page_size": 25
}
| Field Name | Datatype | Description |
|---|---|---|
| report_type | String | Name of the API |
| report_date | String | Date report was run |
| earliest_date_available | String | Earliest Data is Available |
| start_date | String | Start date of report |
| end_date | String | End date of report |
| time_zone | String | Time Zone |
| report_data | Object | Report details object containing Totals object and Campaigns array. Report Data Object |
| global_master_advertiser_id | String | Identifier for advertiser |
| page | Int | Page Number |
| page_size | Int | Number of keywords on page |
| Field Name | Datatype | Description |
|---|---|---|
| keywords | Keyword[] | Array of Keyword |
| unattributed_keywords | Keyword[] | Array of Keyword |
| totals | Object | Total Object |
| Field Name | Datatype | Description |
|---|---|---|
| keyword | Integer | Keyword Name |
| type | Integer | Keyword Type (search/display) |
| clicks | Float | Clicks for Keyword |
| impressions | Integer | Impressions for Keyword |
| ctr | Float | Click through Rate for Keyword |
| Field Name | Datatype | Description |
|---|---|---|
| type | Integer | Keyword Type (search/display) |
| clicks | Float | Clicks for Keyword |
| impressions | Integer | Impressions for Keyword |
| ctr | Float | Click through Rate for Keyword |
| Field Name | Datatype | Description |
|---|---|---|
| keywords | Integer | Number of total keywords regardless of page |
| clicks | Float | Overall Clicks |
| impressions | Integer | Overall Impressions |
| ctr | Float | Overall Click through Rate |
Search Campaign Metrics
Resource Overview
| Method | URI Format |
|---|---|
| GET | /client_reports/search_activity/[gmaid]?[query_params] |
Use GET to retrieve information for the Search Activity report for a given advertiser.
The data returned will include impressions, leads, clicks, calls, qualified_web_events, web_events, emails, and spend values organized by campaign and campaign_cycle.
Parameters
When using the GET method, the results can be filtered using these parameters:
| Param | Function |
|---|---|
| start_date | Restricts the results to those occurring on or after this date |
| end_date | Restricts the results to those occurring on or before this date |
| global_master_campaign_id[] | Restrict results to one or more specific campaigns. This should be a comma separated string. Ex: global_master_campaign_id[]=TEST_1,TEST_2 |
| campaign_status[] | Restrict results to all campaigns with given status values. Allowed values are running, stopped and ended. This should be a comma separated string. Ex: campaign_status[]=running,stopped |
| campaign_cycle | Restrict results to a single campaign cycle |
| interval_size | Use calendar_month or calendar_week to roll up the data points into calendar intervals (default is 1 day per interval) |
| include_cycles | Set to true or false on whether to include cycle nesting. Default value is false |
| include_full_channel | Optional, default: false. Includes all metrics for the search channel. Xmedia campaigns will only contain metrics that belong to the search channel, rather than full campaign metrics. |
To specify a date range:
- Specify start_date and end_date.
- When specifying a campaign_cycle, do not use date range params.
Response Data Details
Retrieve data for a specific range of dates
curl -H "Authorization: Bearer Bearer OAUTH_ACCESS_TOKEN \
https://api.localiqservices.com/client_reports/search_activity/TEST_1?start_date=2016-12-01&end_date=2016-12-31"
Retrieve data for a specific campaign starting on a certain date
curl -g -H "Authorization: Bearer Bearer OAUTH_ACCESS_TOKEN \
https://api.localiqservices.com/client_reports/search_activity/TEST_1?global_master_campaign_id[]=TEST_1&start_date=2016-10-01&end_date=2016-12-31"
Retrieve data for a specific campaign cycle
curl -H "Authorization: Bearer Bearer OAUTH_ACCESS_TOKEN \
https://api.localiqservices.com/client_reports/search_activity/TEST_1?campaign_cycle=TEST_1"
Retrieve data for campaigns that are stopped and running
curl -g -H "Authorization: Bearer Bearer OAUTH_ACCESS_TOKEN \
https://api.localiqservices.com/client_reports/search_activity/TEST_1?&campaign_status[]=running,stopped&start_date=2016-10-01&end_date=2016-12-31"
Retrieve data for a specific campaign starting on a certain date with cycle nesting
curl -g -H "Authorization: Bearer Bearer OAUTH_ACCESS_TOKEN \
https://api.localiqservices.com/client_reports/search_activity/TEST_1?global_master_campaign_id[]=TEST_1&start_date=2016-10-01&end_date=2016-12-31&include_cycles=true"
Example Response if there is a Top Search Campaign (bidding pricing model is 8)
{
"report_type": "search_activity",
"report_date": "2020-10-15",
"earliest_date_available": "2020-01-01",
"start_date": "2020-10-10",
"end_date": "2020-10-10",
"time_zone": "America/Los_Angeles",
"interval_size": "day",
"currency": "USD",
"report_data": {
"campaigns": [
{
"name": "Search Campaign (Demo)",
"global_master_campaign_id": "TEST_1368547",
"start_date": "2020-01-01",
"end_date": null,
"type": "search",
"status": "running",
"bidding_pricing_model_id": 8,
"intervals": [
{
"start_date": "2020-10-10",
"impressions": 1065,
"impression_share": 0,
"leads": 19,
"clicks": 17,
"chats": 9.0,
"calls": 6,
"web_events": 7,
"qualified_web_events": 5,
"emails": 8,
"spend": 25,
"ctr": 1.6,
"cpc": 1.47,
"position": null,
"device_breakdowns": {
"impression_share": {
"mobile": 0,
"desktop": 0,
"tablet": 0
},
"impressions": {
"mobile": 1000,
"desktop": 65,
"tablet": 0
},
"clicks": {
"mobile": 14,
"desktop": 3,
"tablet": 0
}
},
"search_impression_share": 1,
"top_search_impression_share": 1,
"absolute_top_search_impression_share": 1,
"rank_lost_absolute_top_search_impression_share": 1,
"budget_lost_absolute_top_search_impression_share": 1
}
],
"search_impression_share": 1,
"top_search_impression_share": 1,
"absolute_top_search_impression_share": 1,
"rank_lost_absolute_top_search_impression_share": 1,
"budget_lost_absolute_top_search_impression_share": 1
},
{
"name": "Search Campaign (Demo)",
"global_master_campaign_id": "TEST_1368327",
"start_date": "2020-01-01",
"end_date": null,
"type": "search",
"status": "running",
"bidding_pricing_model_id": 1,
"intervals": [
{
"start_date": "2020-10-10",
"impressions": 1065,
"impression_share": 0,
"leads": 19,
"clicks": 17,
"calls": 6,
"web_events": 7,
"qualified_web_events": 5,
"emails": 8,
"spend": 25,
"ctr": 1.6,
"cpc": 1.47,
"position": null,
"device_breakdowns": {
"impression_share": {
"mobile": 0,
"desktop": 0,
"tablet": 0
},
"impressions": {
"mobile": 1000,
"desktop": 65,
"tablet": 0
},
"clicks": {
"mobile": 14,
"desktop": 3,
"tablet": 0
}
}
}
]
}
],
"totals": {
"impressions": 1065,
"clicks": 17,
"chats": 9.0,
"calls": 6,
"web_events": 7,
"qualified_web_events": 5,
"emails": 8,
"leads": 19,
"spend": 25,
"ctr": 1.6,
"cpc": 1.47,
"device_breakdowns": {
"impressions": {
"desktop": {
"total": 65,
"percent": 6.1
},
"mobile": {
"total": 1000,
"percent": 93.9
},
"tablet": {
"total": 0,
"percent": 0
}
},
"clicks": {
"desktop": {
"total": 3,
"percent": 17.65
},
"mobile": {
"total": 14,
"percent": 82.35
},
"tablet": {
"total": 0,
"percent": 0
}
}
},
"position": null,
"search_impression_share": 1,
"top_search_impression_share": 1,
"absolute_top_search_impression_share": 1,
"rank_lost_absolute_top_search_impression_share": 1,
"budget_lost_absolute_top_search_impression_share": 1
},
"totals_per_interval": [
{
"start_date": "2020-10-10",
"impressions": 1065,
"impression_share": 0,
"leads": 19,
"clicks": 17,
"chats": 9.0,
"calls": 6,
"web_events": 7,
"qualified_web_events": 5,
"emails": 8,
"spend": 25,
"ctr": 1.6,
"cpc": 1.47,
"position": null,
"device_breakdowns": {
"impression_share": {
"mobile": 0,
"desktop": 0,
"tablet": 0
},
"impressions": {
"mobile": 1000,
"desktop": 65,
"tablet": 0
},
"clicks": {
"mobile": 14,
"desktop": 3,
"tablet": 0
}
},
"search_impression_share": 1,
"top_search_impression_share": 1,
"absolute_top_search_impression_share": 1,
"rank_lost_absolute_top_search_impression_share": 1,
"budget_lost_absolute_top_search_impression_share": 1
}
]
},
"global_master_advertiser_id": "TEST_1"
}
| Field Name | Datatype | Description |
|---|---|---|
| report_type | String | Type of report |
| report_date | String | Date report ran |
| earliest_date_available | String | How far back data is available |
| start_date | String | Start date of report |
| end_date | String | End date of report |
| time_zone | String | Time Zone |
| interval_size | String | Interval Size ('day', 'calendar_week' or 'calendar_month') |
| currency | String | Currency for Advertiser |
| report_data | Object | Report Data Object. |
| global_master_advertiser_id | String | Identifier for advertiser |
| Field Name | Datatype | Description |
|---|---|---|
| campaigns | Array | All data for campigns. Campaigns Array. |
| totals | Object | Totals data. Totals Details. |
| totals_per_interval | Array | Totals per interval over multiple campaigns. Totals Per Interval Details. |
| Field Name | Datatype | Description |
|---|---|---|
| name | String | Campaign name |
| global_master_campaign_id | String | Identifier for campaign |
| start_date | String | Start date for campaign |
| end_date | String | End date for campaign |
| type | String | Type of campaign |
| status | String | Status of campaign |
| bidding_pricing_model_id | Integer | The id which will be used to filter the sub type of top search campaign |
| intervals | Array | Data for specified interval. Intervals Array. |
| Field Name | Datatype | Description |
|---|---|---|
| start_date | String | Start date of interval |
| impressions | Integer | Impressions for interval |
| impression_share | Integer | Impression share for interval |
| leads | Integer | Leads for interval |
| clicks | Integer | Clicks for interval |
| chats | Integer | Chats for interval |
| calls | Integer | Calls for interval |
| web_events | Integer | Web events for interval |
| qualified_web_events | Integer | A lead generating CVT/Web Event |
| emails | Integer | Emails for interval |
| spend | Integer | Spend for interval |
| ctr | Integer | Click through rate for interval |
| cpc | Integer | Cost per click for interval |
| device_breakdowns | DeviceBreakdown[] | Array of DeviceBreakdown |
| search_impression_share | Integer | Search impression share for interval |
| top_search_impression_share | Integer | Top Search impression share for interval |
| absolute_top_search_impression_share | Integer | Absolute Top Search Impression share for interval |
| rank_lost_absolute_top_search_impression_share | Integer | Rank Lost Absolute Top Search Impression share for interval |
| budget_lost_absolute_top_search_impression_share | Integer | Budget Lost Absolute Top Search Impression share for interval |
| Field Name | Datatype | Description |
|---|---|---|
| impressions | Integer | Total impressions |
| clicks | Integer | Total click events |
| chats | Integer | Total chat generated by paid traffic |
| calls | Integer | Total call events |
| web_events | Integer | Total web events |
| qualified_web_events | Integer | A lead generating CVT/Web Event |
| emails | Integer | Total email events |
| leads | Integer | Total leads |
| spend | Integer | Total spend |
| ctr | Integer | Total click through rate |
| cpc | Integer | Toal cost per click |
| device_breakdowns | DeviceBreakdown[] | Array of DeviceBreakdown |
| search_impression_share | Decimal | Search impression share percentage for interval |
| top_search_impression_share | Decimal | Top Search impression share percentage for interval |
| absolute_top_search_impression_share | Decimal | Absolute Top Search Impression share percentage for interval |
| rank_lost_absolute_top_search_impression_share | Decimal | Rank Lost Absolute Top Search Impression share percentage for interval |
| budget_lost_absolute_top_search_impression_share | Decimal | Budget Lost Absolute Top Search Impression share percentage for interval |
| Field Name | Datatype | Description |
|---|---|---|
| Impressions | Object | Device breakdown of impressions. Impressions Object. |
| Impression Share | Object | Device breakdown of impression share. Impression Share Object. |
| Clicks | Object | Device breakdown of clicks. Clicks Object |
| Field Name | Datatype | Description |
|---|---|---|
| desktop | Object | Total and percent of total for impressions of desktop |
| mobile | Object | Total and percent of total for impressions of mobile |
| tablet | Object | Total and percent of total for impressions of tablet |
| Field Name | Datatype | Description |
|---|---|---|
| desktop | Object | Percent impression share of desktop |
| mobile | Object | Percent impression share of mobile |
| tablet | Object | Percent impression share of tablet |
| Field Name | Datatype | Description |
|---|---|---|
| desktop | Object | Total and percent of total for clicks of desktop |
| mobile | Object | Total and percent of total for clicks of mobile |
| tablet | Object | Total and percent of total for clicks of tablet |
This is an Interval object across all campaigns.
| Field Name | Datatype | Description |
|---|---|---|
| campaign_cycle | String | Name of cycle |
| start_date | String | Start date of cycle |
| end_date | String | End date of cycle |
| intervals | Array | Data for specified interval. Intervals Array. |
Google Keyword Performance
Resource Overview
| Method | URI Format |
|---|---|
| GET | /client_reports/google_keyword/[gmaid]?[query_params] |
Use GET to retrieve information for the Keyword Google Compliance Report. Data can be returned in different intervals determined by the range. The requirements for these parameters are described below.
The data returned will include google only totals for impressions, clicks, click-through-rate (CTR), media_cost, keywords, and average position. It will also show breakdowns per keyword for clicks, media cost, impressions, average position, first page cost-per-click (CPC) and top page cost-per-click. Data will be returned in pages, controlled by the parameters page and page_size. The first page is page 1. Default values of 1 and 15 will be used if not specified. Data is sorted in alphabetical order by keyword.
Note: This API will not provide an Average page position from 1/1/2020 onward in the response.
Parameters
When using the GET method, the results can be filtered using these parameters:
| Parameter | Required | Description |
|---|---|---|
| start_date | Yes | Restricts the results to those occurring on or after this date. |
| end_date | Yes | Restricts the results to those occurring on or before this date. |
| global_master_campaign_id[] | No | Restrict results to one or more specific campaigns. This should be a comma separated string. Ex: global_master_campaign_id[]=USA_123,USA_456 |
| campaign_status[] | No | Restrict results to all campaigns with given status values. Allowed values are running, stopped and ended`. This should be a comma separated string. Ex: campaign_status[]=running,stopped |
| page_size | No | Restrict number of keywords in result. Default value: 15 |
| page | No | Specifies which page of results to return. Default value: 1 |
| sort_by | No | Specifies what column to sort by. Valid columns are: keyword, clicks, media cost, impressions, avg_position, first_page_cpc, top_page_cpc. Default value: keyword |
| sort_dir | No | Specifies the sort direction. Can be either asc or desc. Default value: asc |
Response Data Details
Retrieve data for a specific range of dates
curl -H "Authorization: Bearer OAUTH_ACCESS_TOKEN \
https://api.localiqservices.com/client_reports/google_keyword/TEST_1?start_date=2016-12-01&end_date=2016-12-31&page=1&page_size=15"
Retrieve data for a specific campaign starting on a certain date
curl -g -H "Authorization: Bearer OAUTH_ACCESS_TOKEN \
https://api.localiqservices.com/client_reports/google_keyword/TEST_1?global_master_campaign_id[]=TEST_1&start_date=2016-10-01&end_date=2016-12-31&page=1&page_size=15"
Retrieve data for campaigns that are stopped and running
curl -g -H "Authorization: Bearer OAUTH_ACCESS_TOKEN \
https://api.localiqservices.com/client_reports/google_keyword/TEST_1?&campaign_status[]=running,stopped&start_date=2016-10-01&end_date=2016-12-31&page=1&page_size=15"
Example Response
{
"report_type": "google_keyword",
"report_date": "2020-10-15",
"earliest_date_available": "2020-01-01",
"start_date": "2020-10-10",
"end_date": "2020-10-10",
"time_zone": "America/Los_Angeles",
"report_data": {
"totals": {
"clicks": 17,
"media_cost": 918.68,
"impressions": 1065,
"ctr": 1.6,
"keywords": 2
},
"keywords": [
{
"keyword": "Keyword (Demo) 1 Location (Demo) 1",
"clicks": 6,
"media_cost": 0,
"impressions": 383,
"first_page_cpc": 7.34,
"top_page_cpc": 16
},
{
"keyword": "Keyword (Demo) 2 Location (Demo) 2",
"clicks": 11,
"media_cost": 0,
"impressions": 682,
"first_page_cpc": 7.34,
"top_page_cpc":15
}
],
"unattributed_keywords": [
{
"type": "search",
"clicks": 12,
"impressions": 62,
"ctr": 19.35
}
]
},
"global_master_advertiser_id": "TEST_1",
"page": 1,
"page_size": 25
}
| Field Name | Datatype | Description |
|---|---|---|
| report_type | String | Name of the API |
| report_date | String | Date report was run |
| earliest_date_available | String | Earliest Data is Available |
| start_date | String | Start date of report |
| end_date | String | End date of report |
| time_zone | String | Time Zone |
| report_data | Object | Report details object containing Totals object and Campaigns array. Report Data Object |
| global_master_advertiser_id | String | Identifier for advertiser |
| page | Integer | Page Number |
| page_size | Integer | Number of keywords on page |
| Field Name | Datatype | Description |
|---|---|---|
| keywords | Array | Array of Keyword Object |
| unattributed_keywords | Array | Array of Keyword Object |
| totals | Object | Total Object |
| Field Name | Datatype | Description |
|---|---|---|
| keyword | Integer | Keyword Name |
| type | Integer | Keyword Type (search/display) |
| clicks | Float | Clicks for Keyword |
| media_cost | Float | cost |
| impressions | Integer | Impressions for Keyword |
| ctr | Float | Click through Rate for Keyword |
| Field Name | Datatype | Description |
|---|---|---|
| type | Integer | Keyword Type (search/display) |
| clicks | Float | Clicks for Keyword |
| impressions | Integer | Impressions for Keyword |
| ctr | Float | Click through Rate for Keyword |
| Field Name | Datatype | Description |
|---|---|---|
| keywords | Integer | Number of total keywords regardless of page |
| clicks | Float | Overall Clicks |
| media_cost | Float | cost |
| impressions | Integer | Overall Impressions |
| ctr | Float | Overall Click through Rate |
Google Search Metrics
Resource Overview
| Method | URI Format |
|---|---|
| GET | /client_reports/google_search_activity/[gmaid]?[query_params] |
Use GET to retrieve the Google Search Activity Compliance report for a given advertiser.
The data returned will include impressions, clicks, and media cost values organized by campaign and campaign_cycle.
Parameters
When using the GET method, the results can be filtered using these parameters:
| Param | Function |
|---|---|
| start_date | Restricts the results to those occurring on or after this date |
| end_date | Restricts the results to those occurring on or before this date |
| global_master_campaign_id[] | Restrict results to one or more specific campaigns. This should be a comma separated string. Ex: global_master_campaign_id[]=TEST_1,TEST_2 |
| campaign_status[] | Restrict results to all campaigns with given status values. Allowed values are running, stopped and ended. This should be a comma separated string. Ex: campaign_status[]=running,stopped |
| campaign_cycle | Restrict results to a single campaign cycle |
| interval_size | Use calendar_month or calendar_week to roll up the data points into calendar intervals (default is 1 day per interval) |
| include_cycles | Set to true or false on whether to include cycle nesting. Default value is false |
To specify a date range:
- Specify start_date and end_date.
- When specifying a campaign_cycle, do not use date range params.
Response Data Details
Retrieve data for a specific range of dates
curl -H "Authorization: Bearer OAUTH_ACCESS_TOKEN \
https://api.localiqservices.com/client_reports/google_search_activity/TEST_1?start_date=2016-12-01&end_date=2016-12-31"
Retrieve data for a specific campaign starting on a certain date
curl -g -H "Authorization: Bearer OAUTH_ACCESS_TOKEN \
https://api.localiqservices.com/client_reports/google_search_activity/TEST_1?global_master_campaign_id[]=TEST_1&start_date=2016-10-01&end_date=2016-12-31"
Retrieve data for a specific campaign cycle
curl -H "Authorization: Bearer OAUTH_ACCESS_TOKEN \
https://api.localiqservices.com/client_reports/google_search_activity/TEST_1?campaign_cycle=TEST_1"
Retrieve data for campaigns that are stopped and running
curl -g -H Authorization: Bearer OAUTH_ACCESS_TOKEN" \
https://api.localiqservices.com/client_reports/google_search_activity/TEST_1?&campaign_status[]=running,stopped&start_date=2016-10-01&end_date=2016-12-31"
Retrieve data for a specific campaign starting on a certain date with cycle nesting
curl -g -H "Authorization: Bearer OAUTH_ACCESS_TOKEN \
https://api.localiqservices.com/client_reports/google_search_activity/TEST_1?global_master_campaign_id[]=TEST_1&start_date=2016-10-01&end_date=2016-12-31&include_cycles=true"
Example Response
{
"report_type": "google_search_activity",
"report_date": "2020-10-16",
"earliest_date_available": "2020-01-01",
"start_date": "2020-10-10",
"end_date": "2020-10-10",
"time_zone": "America/Los_Angeles",
"interval_size": "day",
"currency": "USD",
"report_data": {
"campaigns": [
{
"name": "Search Campaign (Demo)",
"global_master_campaign_id": "TEST_1368547",
"start_date": "2020-01-01",
"end_date": null,
"type": "search",
"status": "running",
"intervals": [
{
"start_date": "2020-10-10",
"impressions": 1065,
"clicks": 17,
"media_cost": 25
}
]
}
],
"totals": {
"impressions": 1065,
"clicks": 17,
"media_cost": 25
},
"totals_per_interval": [
{
"start_date": "2020-10-10",
"impressions": 1065,
"clicks": 17,
"media_cost": 25
}
]
},
"global_master_advertiser_id": "TEST_1"
}
| Field Name | Datatype | Description |
|---|---|---|
| report_type | String | Type of report |
| report_date | String | Date report ran |
| earliest_date_available | String | How far back data is available |
| start_date | String | Start date of report |
| end_date | String | End date of report |
| time_zone | String | Time Zone |
| interval_size | String | Interval Size ('day', 'calendar_week' or 'calendar_month') |
| currency | String | Currency for Advertiser |
| report_data | Object | Report Data Object. |
| global_master_advertiser_id | String | Identifier for advertiser |
Report Data Object
| Field Name | Datatype | Description |
|---|---|---|
| campaigns | Array | All data for campigns. Campaigns Array. |
| totals | Object | Totals data. Totals Details. |
| totals_per_interval | Array | Totals per interval over multiple campaigns. Totals Per Interval Details. |
| Field Name | Datatype | Description |
|---|---|---|
| name | String | Campaign name |
| global_master_campaign_id | String | Identifier for campaign |
| start_date | String | Start date for campaign |
| end_date | String | End date for campaign |
| type | String | Type of campaign |
| status | String | Status of campaign |
| intervals | Interval[] | Array of Interval Intervals Array. |
| Field Name | Datatype | Description |
|---|---|---|
| start_date | String | Start date of interval |
| impressions | Integer | Impressions for interval |
| clicks | Integer | Clicks for interval |
| media_cost | Float | Cost for interval |
| Field Name | Datatype | Description |
|---|---|---|
| impressions | Integer | Total Impressions |
| clicks | Integer | Total Clicks |
| media_cost | Float | Total Cost |
This is an Interval object across all campaigns.
Social APIs
SocialAds Campaign Metrics
Resource Overview
| Method | URI Format |
|---|---|
| GET | /client_reports/facebook_campaign/[gmaid]?[query_params] |
Use GET to retrieve information for the SocialAds Campaign Report for a given advertiser.
The data returned will include various metrics organized by campaign and campaign_cycle. If no values are present for a given metric, 0 is assumed, except for offline_conversion_purchases, offline_conversion_purchases_value, cpsc and roas, which will be omitted from the result if not present.
Parameters
When using the GET method, the results can be filtered using these parameters:
| Param | Function |
|---|---|
| start_date | Restricts the results to those occurring on or after this date |
| end_date | Restricts the results to those occurring on or before this date |
| global_master_campaign_id[] | Restrict results to one or more specific campaigns. This should be a comma separated string. Ex: global_master_campaign_id[]=TEST_1,TEST_2 |
| campaign_status[] | Restrict results to all campaigns with given status values. Allowed values are running, stopped and ended. This should be a comma separated string. Ex: campaign_status[]=running,stopped |
| campaign_cycle | Restrict results to a single campaign cycle |
| interval_size | Use calendar_month or calendar_week to roll up the data points into calendar intervals (default is 1 day per interval) |
| include_cycles | Set to true or false on whether to include cycle nesting. Default value is false |
| focus | Optional. Value must be goal |
| goal_type_ids[] | Optional. Focus must be specified as goal. Must be an array of valid goal_type_ids |
| include_full_channel | Optional, default: false. Includes all metrics for the social channel. Xmedia campaigns will only contain metrics that are categorized as social, rather than full campaign metrics. |
To specify a date range
- Specify start_date and end_date.
- When specifying a campaign_cycle, do not use date range params.
Valid Goal Type Ids
| Goal Type Id | Goal Types |
|---|---|
| 1 | CPL |
| 2 | Calls |
| 3 | Contacts |
| 4 | Engagement |
| 5 | Reach |
| 6 | Contacts (Dynamic Ads - Automotive) |
| 7 | Sales |
Response Data Details
Retrieve data for a specific range of dates
curl -H "Authorization: Bearer OAUTH_ACCESS_TOKEN" \
https://api.localiqservices.com/client_reports/facebook_campaign/TEST_1?start_date=2016-12-01&end_date=2016-12-31
Retrieve data for a specific campaign starting on a certain date
curl -g -H "Authorization: Bearer OAUTH_ACCESS_TOKEN" \
https://api.localiqservices.com/client_reports/facebook_campaign/TEST_1?global_master_campaign_id[]=TEST_1&start_date=2016-10-01&end_date=2016-12-31
Retrieve data for a specific campaign cycle
curl -H "Authorization: Bearer OAUTH_ACCESS_TOKEN" \
https://api.localiqservices.com/client_reports/facebook_campaign/TEST_1?campaign_cycle=TEST_1
Retrieve data for campaigns that are stopped and running
curl -g -H "Authorization: Bearer OAUTH_ACCESS_TOKEN" \
https://api.localiqservices.com/client_reports/facebook_campaign/TEST_1?&campaign_status[]=running,stopped&start_date=2016-12-01&end_date=2016-12-31
Retrieve data for a specific campaign starting on a certain date with cycle nesting
curl -g -H "Authorization: Bearer OAUTH_ACCESS_TOKEN" \
https://api.localiqservices.com/client_reports/facebook_campaign/TEST_1?global_master_campaign_id[]=TEST_1&start_date=2016-12-01&end_date=2016-12-31&include_cycles=true
Example Response:
curl -g -H "Authorization: Bearer OAUTH_ACCESS_TOKEN" \
https://api.localiqservices.com/client_reports/facebook_campaign/TEST_1?start_date=2020-06-26&end_date=2020-06-27
Example Response
{
"report_type": "facebook_campaign",
"report_date": "2020-10-15",
"earliest_date_available": "2020-01-01",
"start_date": "2020-10-10",
"end_date": "2020-10-10",
"time_zone": "America/Los_Angeles",
"interval_size": "day",
"currency": "USD",
"report_data": {
"campaigns": [
{
"name": "Facebook Campaign (Demo)",
"global_master_campaign_id": "TEST_1368565",
"start_date": "2020-01-01",
"end_date": null,
"type": "display",
"status": "running",
"goals": [
{
"goal_type_id": 4,
"goal_type": "Engagement"
},
{
"goal_type_id": 5,
"goal_type": "Reach"
}
],
"intervals": [
{
"start_date": "2020-10-10",
"impressions": 1403,
"call_to_action_clicks": 5,
"clicks": 16,
"social_clicks": 10,
"reach": 1403,
"social_reach": 70,
"social_impressions": 1403,
"website_clicks": 8,
"inline_link_clicks": 5,
"link_click": 9,
"page_engagement": 77,
"like": 85,
"post_engagement": 84,
"comment": 8,
"post": 9,
"post_reaction": 65,
"checkin": 8,
"action_reaction": 9,
"leadgen.other": 0,
"frequency": 5,
"spend": 25,
"video_p100_watched_actions": 20,
"video_avg_percent_watched_actions": 76,
"offline_conversion_purchases": 7,
"offline_conversion_purchases_value": 82,
"leads": 18,
"cpc": 1.56,
"cpm": 17.82,
"ctr": 1.14,
"cpsc": 3.57,
"roas": 328
}
]
}
],
"totals": {
"impressions_breakdown": {
"age_18-24_gender_male": 60061.0,
"age_18-24_gender_female": 58497.0,
"age_25-34_gender_male": 126873.0,
"age_25-34_gender_female": 77115.0,
"age_35-44_gender_male": 64724.0,
"age_35-44_gender_female": 36731.0,
"age_45-54_gender_male": 39743.0,
"age_45-54_gender_female": 20413.0,
"age_55-64_gender_male": 29282.0,
"age_55-64_gender_female": 21530.0,
"age_65+_gender_male": 22916.0,
"age_65+_gender_female": 20473.0,
"age_13-17_gender_male": 0,
"age_13-17_gender_female": 0,
"age_18-24_gender_unknown": 367.0,
"age_25-34_gender_unknown": 1014.0,
"age_35-44_gender_unknown": 679.0,
"age_45-54_gender_unknown": 269.0,
"age_55-64_gender_unknown": 378.0,
"age_65+_gender_unknown": 282.0,
"age_13-17_gender_unknown": 0,
"device_other": 2915.0,
"device_desktop": 32776.0,
"device_iphone": 274083.0,
"device_ipad": 7901.0,
"device_ipod": 120.0,
"device_android_smartphone": 257281.0,
"device_android_tablet": 6271.0,
"age_Unknown_gender_male": 0,
"age_Unknown_gender_female": 0,
"age_Unknown_gender_unknown": 0
},
"call_to_action_clicks_breakdown": {
"age_18-24_gender_male": 0,
"age_18-24_gender_female": 0,
"age_25-34_gender_male": 0,
"age_25-34_gender_female": 0,
"age_35-44_gender_male": 0,
"age_35-44_gender_female": 0,
"age_45-54_gender_male": 0,
"age_45-54_gender_female": 0,
"age_55-64_gender_male": 0,
"age_55-64_gender_female": 0,
"age_65+_gender_male": 0,
"age_65+_gender_female": 0,
"age_13-17_gender_male": 0,
"age_13-17_gender_female": 0,
"age_18-24_gender_unknown": 0,
"age_25-34_gender_unknown": 0,
"age_35-44_gender_unknown": 0,
"age_45-54_gender_unknown": 0,
"age_55-64_gender_unknown": 0,
"age_65+_gender_unknown": 0,
"age_13-17_gender_unknown": 0,
"device_other": 0,
"device_desktop": 0,
"device_iphone": 0,
"device_ipad": 0,
"device_ipod": 0,
"device_android_smartphone": 0,
"device_android_tablet": 0,
"age_Unknown_gender_male": 0,
"age_Unknown_gender_female": 0,
"age_Unknown_gender_unknown": 0
},
"clicks_breakdown": {
"age_18-24_gender_male": 183.0,
"age_18-24_gender_female": 123.0,
"age_25-34_gender_male": 234.0,
"age_25-34_gender_female": 150.0,
"age_35-44_gender_male": 130.0,
"age_35-44_gender_female": 85.0,
"age_45-54_gender_male": 87.0,
"age_45-54_gender_female": 69.0,
"age_55-64_gender_male": 128.0,
"age_55-64_gender_female": 151.0,
"age_65+_gender_male": 175.0,
"age_65+_gender_female": 223.0,
"age_13-17_gender_male": 0,
"age_13-17_gender_female": 0,
"age_18-24_gender_unknown": 0,
"age_25-34_gender_unknown": 1.0,
"age_35-44_gender_unknown": 1.0,
"age_45-54_gender_unknown": 0,
"age_55-64_gender_unknown": 4.0,
"age_65+_gender_unknown": 0,
"age_13-17_gender_unknown": 0,
"device_other": 16.0,
"device_desktop": 71.0,
"device_iphone": 615.0,
"device_ipad": 85.0,
"device_ipod": 0,
"device_android_smartphone": 891.0,
"device_android_tablet": 66.0,
"age_Unknown_gender_male": 0,
"age_Unknown_gender_female": 0,
"age_Unknown_gender_unknown": 0
},
"social_clicks_breakdown": {
"age_18-24_gender_male": 0,
"age_18-24_gender_female": 0,
"age_25-34_gender_male": 0,
"age_25-34_gender_female": 0,
"age_35-44_gender_male": 0,
"age_35-44_gender_female": 0,
"age_45-54_gender_male": 0,
"age_45-54_gender_female": 0,
"age_55-64_gender_male": 0,
"age_55-64_gender_female": 0,
"age_65+_gender_male": 0,
"age_65+_gender_female": 0,
"age_13-17_gender_male": 0,
"age_13-17_gender_female": 0,
"age_18-24_gender_unknown": 0,
"age_25-34_gender_unknown": 0,
"age_35-44_gender_unknown": 0,
"age_45-54_gender_unknown": 0,
"age_55-64_gender_unknown": 0,
"age_65+_gender_unknown": 0,
"age_13-17_gender_unknown": 0,
"device_other": 0,
"device_desktop": 0,
"device_iphone": 0,
"device_ipad": 0,
"device_ipod": 0,
"device_android_smartphone": 0,
"device_android_tablet": 0,
"age_Unknown_gender_male": 0,
"age_Unknown_gender_female": 0,
"age_Unknown_gender_unknown": 0
},
"reach_breakdown": {
"age_18-24_gender_male": 57744.0,
"age_18-24_gender_female": 54131.0,
"age_25-34_gender_male": 123207.0,
"age_25-34_gender_female": 73048.0,
"age_35-44_gender_male": 61341.0,
"age_35-44_gender_female": 34512.0,
"age_45-54_gender_male": 36355.0,
"age_45-54_gender_female": 18871.0,
"age_55-64_gender_male": 26896.0,
"age_55-64_gender_female": 19463.0,
"age_65+_gender_male": 19927.0,
"age_65+_gender_female": 16737.0,
"age_13-17_gender_male": 0,
"age_13-17_gender_female": 0,
"age_18-24_gender_unknown": 325.0,
"age_25-34_gender_unknown": 958.0,
"age_35-44_gender_unknown": 599.0,
"age_45-54_gender_unknown": 209.0,
"age_55-64_gender_unknown": 302.0,
"age_65+_gender_unknown": 222.0,
"age_13-17_gender_unknown": 0,
"device_other": 2715.0,
"device_desktop": 27900.0,
"device_iphone": 264095.0,
"device_ipad": 7323.0,
"device_ipod": 79.0,
"device_android_smartphone": 241351.0,
"device_android_tablet": 5427.0,
"age_Unknown_gender_male": 0,
"age_Unknown_gender_female": 0,
"age_Unknown_gender_unknown": 0
},
"social_impressions_breakdown": {
"age_18-24_gender_male": 0,
"age_18-24_gender_female": 0,
"age_25-34_gender_male": 0,
"age_25-34_gender_female": 0,
"age_35-44_gender_male": 0,
"age_35-44_gender_female": 0,
"age_45-54_gender_male": 0,
"age_45-54_gender_female": 0,
"age_55-64_gender_male": 0,
"age_55-64_gender_female": 0,
"age_65+_gender_male": 0,
"age_65+_gender_female": 0,
"age_13-17_gender_male": 0,
"age_13-17_gender_female": 0,
"age_18-24_gender_unknown": 0,
"age_25-34_gender_unknown": 0,
"age_35-44_gender_unknown": 0,
"age_45-54_gender_unknown": 0,
"age_55-64_gender_unknown": 0,
"age_65+_gender_unknown": 0,
"age_13-17_gender_unknown": 0,
"device_other": 0,
"device_desktop": 0,
"device_iphone": 0,
"device_ipad": 0,
"device_ipod": 0,
"device_android_smartphone": 0,
"device_android_tablet": 0,
"age_Unknown_gender_male": 0,
"age_Unknown_gender_female": 0,
"age_Unknown_gender_unknown": 0
},
"website_clicks_breakdown": {
"age_18-24_gender_male": 0,
"age_18-24_gender_female": 0,
"age_25-34_gender_male": 0,
"age_25-34_gender_female": 0,
"age_35-44_gender_male": 0,
"age_35-44_gender_female": 0,
"age_45-54_gender_male": 0,
"age_45-54_gender_female": 0,
"age_55-64_gender_male": 0,
"age_55-64_gender_female": 0,
"age_65+_gender_male": 0,
"age_65+_gender_female": 0,
"age_13-17_gender_male": 0,
"age_13-17_gender_female": 0,
"age_18-24_gender_unknown": 0,
"age_25-34_gender_unknown": 0,
"age_35-44_gender_unknown": 0,
"age_45-54_gender_unknown": 0,
"age_55-64_gender_unknown": 0,
"age_65+_gender_unknown": 0,
"age_13-17_gender_unknown": 0,
"device_other": 0,
"device_desktop": 0,
"device_iphone": 0,
"device_ipad": 0,
"device_ipod": 0,
"device_android_smartphone": 0,
"device_android_tablet": 0,
"age_Unknown_gender_male": 0,
"age_Unknown_gender_female": 0,
"age_Unknown_gender_unknown": 0
},
"link_click_breakdown": {
"age_18-24_gender_male": 8.0,
"age_18-24_gender_female": 8.0,
"age_25-34_gender_male": 13.0,
"age_25-34_gender_female": 13.0,
"age_35-44_gender_male": 5.0,
"age_35-44_gender_female": 2.0,
"age_45-54_gender_male": 5.0,
"age_45-54_gender_female": 5.0,
"age_55-64_gender_male": 6.0,
"age_55-64_gender_female": 15.0,
"age_65+_gender_male": 13.0,
"age_65+_gender_female": 21.0,
"age_13-17_gender_male": 0,
"age_13-17_gender_female": 0,
"age_18-24_gender_unknown": 0,
"age_25-34_gender_unknown": 0,
"age_35-44_gender_unknown": 1.0,
"age_45-54_gender_unknown": 0,
"age_55-64_gender_unknown": 0,
"age_65+_gender_unknown": 0,
"age_13-17_gender_unknown": 0,
"device_other": 1.0,
"device_desktop": 5.0,
"device_iphone": 32.0,
"device_ipad": 7.0,
"device_ipod": 0,
"device_android_smartphone": 61.0,
"device_android_tablet": 9.0,
"age_Unknown_gender_male": 0,
"age_Unknown_gender_female": 0,
"age_Unknown_gender_unknown": 0
},
"page_engagement_breakdown": {
"age_18-24_gender_male": 8.0,
"age_18-24_gender_female": 8.0,
"age_25-34_gender_male": 14.0,
"age_25-34_gender_female": 13.0,
"age_35-44_gender_male": 5.0,
"age_35-44_gender_female": 2.0,
"age_45-54_gender_male": 5.0,
"age_45-54_gender_female": 5.0,
"age_55-64_gender_male": 6.0,
"age_55-64_gender_female": 15.0,
"age_65+_gender_male": 14.0,
"age_65+_gender_female": 22.0,
"age_13-17_gender_male": 0,
"age_13-17_gender_female": 0,
"age_18-24_gender_unknown": 0,
"age_25-34_gender_unknown": 0,
"age_35-44_gender_unknown": 1.0,
"age_45-54_gender_unknown": 0,
"age_55-64_gender_unknown": 0,
"age_65+_gender_unknown": 0,
"age_13-17_gender_unknown": 0,
"device_other": 1.0,
"device_desktop": 5.0,
"device_iphone": 33.0,
"device_ipad": 8.0,
"device_ipod": 0,
"device_android_smartphone": 62.0,
"device_android_tablet": 9.0,
"age_Unknown_gender_male": 0,
"age_Unknown_gender_female": 0,
"age_Unknown_gender_unknown": 0
},
"like_breakdown": {
"age_18-24_gender_male": 0,
"age_18-24_gender_female": 0,
"age_25-34_gender_male": 0,
"age_25-34_gender_female": 0,
"age_35-44_gender_male": 0,
"age_35-44_gender_female": 0,
"age_45-54_gender_male": 0,
"age_45-54_gender_female": 0,
"age_55-64_gender_male": 0,
"age_55-64_gender_female": 0,
"age_65+_gender_male": 0,
"age_65+_gender_female": 0,
"age_13-17_gender_male": 0,
"age_13-17_gender_female": 0,
"age_18-24_gender_unknown": 0,
"age_25-34_gender_unknown": 0,
"age_35-44_gender_unknown": 0,
"age_45-54_gender_unknown": 0,
"age_55-64_gender_unknown": 0,
"age_65+_gender_unknown": 0,
"age_13-17_gender_unknown": 0,
"device_other": 0,
"device_desktop": 0,
"device_iphone": 0,
"device_ipad": 0,
"device_ipod": 0,
"device_android_smartphone": 0,
"device_android_tablet": 0,
"age_Unknown_gender_male": 0,
"age_Unknown_gender_female": 0,
"age_Unknown_gender_unknown": 0
},
"post_engagement_breakdown": {
"age_18-24_gender_male": 8.0,
"age_18-24_gender_female": 8.0,
"age_25-34_gender_male": 14.0,
"age_25-34_gender_female": 13.0,
"age_35-44_gender_male": 5.0,
"age_35-44_gender_female": 2.0,
"age_45-54_gender_male": 5.0,
"age_45-54_gender_female": 5.0,
"age_55-64_gender_male": 6.0,
"age_55-64_gender_female": 15.0,
"age_65+_gender_male": 14.0,
"age_65+_gender_female": 22.0,
"age_13-17_gender_male": 0,
"age_13-17_gender_female": 0,
"age_18-24_gender_unknown": 0,
"age_25-34_gender_unknown": 0,
"age_35-44_gender_unknown": 1.0,
"age_45-54_gender_unknown": 0,
"age_55-64_gender_unknown": 0,
"age_65+_gender_unknown": 0,
"age_13-17_gender_unknown": 0,
"device_other": 1.0,
"device_desktop": 5.0,
"device_iphone": 33.0,
"device_ipad": 8.0,
"device_ipod": 0,
"device_android_smartphone": 62.0,
"device_android_tablet": 9.0,
"age_Unknown_gender_male": 0,
"age_Unknown_gender_female": 0,
"age_Unknown_gender_unknown": 0
},
"comment_breakdown": {
"age_18-24_gender_male": 0,
"age_18-24_gender_female": 0,
"age_25-34_gender_male": 0,
"age_25-34_gender_female": 0,
"age_35-44_gender_male": 0,
"age_35-44_gender_female": 0,
"age_45-54_gender_male": 0,
"age_45-54_gender_female": 0,
"age_55-64_gender_male": 0,
"age_55-64_gender_female": 0,
"age_65+_gender_male": 0,
"age_65+_gender_female": 0,
"age_13-17_gender_male": 0,
"age_13-17_gender_female": 0,
"age_18-24_gender_unknown": 0,
"age_25-34_gender_unknown": 0,
"age_35-44_gender_unknown": 0,
"age_45-54_gender_unknown": 0,
"age_55-64_gender_unknown": 0,
"age_65+_gender_unknown": 0,
"age_13-17_gender_unknown": 0,
"device_other": 0,
"device_desktop": 0,
"device_iphone": 0,
"device_ipad": 0,
"device_ipod": 0,
"device_android_smartphone": 0,
"device_android_tablet": 0,
"age_Unknown_gender_male": 0,
"age_Unknown_gender_female": 0,
"age_Unknown_gender_unknown": 0
},
"post_breakdown": {
"age_18-24_gender_male": 0,
"age_18-24_gender_female": 0,
"age_25-34_gender_male": 0,
"age_25-34_gender_female": 0,
"age_35-44_gender_male": 0,
"age_35-44_gender_female": 0,
"age_45-54_gender_male": 0,
"age_45-54_gender_female": 0,
"age_55-64_gender_male": 0,
"age_55-64_gender_female": 0,
"age_65+_gender_male": 0,
"age_65+_gender_female": 0,
"age_13-17_gender_male": 0,
"age_13-17_gender_female": 0,
"age_18-24_gender_unknown": 0,
"age_25-34_gender_unknown": 0,
"age_35-44_gender_unknown": 0,
"age_45-54_gender_unknown": 0,
"age_55-64_gender_unknown": 0,
"age_65+_gender_unknown": 0,
"age_13-17_gender_unknown": 0,
"device_other": 0,
"device_desktop": 0,
"device_iphone": 0,
"device_ipad": 0,
"device_ipod": 0,
"device_android_smartphone": 0,
"device_android_tablet": 0,
"age_Unknown_gender_male": 0,
"age_Unknown_gender_female": 0,
"age_Unknown_gender_unknown": 0
},
"post_reaction_breakdown": {
"age_18-24_gender_male": 0,
"age_18-24_gender_female": 0,
"age_25-34_gender_male": 1.0,
"age_25-34_gender_female": 0,
"age_35-44_gender_male": 0,
"age_35-44_gender_female": 0,
"age_45-54_gender_male": 0,
"age_45-54_gender_female": 0,
"age_55-64_gender_male": 0,
"age_55-64_gender_female": 0,
"age_65+_gender_male": 1.0,
"age_65+_gender_female": 1.0,
"age_13-17_gender_male": 0,
"age_13-17_gender_female": 0,
"age_18-24_gender_unknown": 0,
"age_25-34_gender_unknown": 0,
"age_35-44_gender_unknown": 0,
"age_45-54_gender_unknown": 0,
"age_55-64_gender_unknown": 0,
"age_65+_gender_unknown": 0,
"age_13-17_gender_unknown": 0,
"device_other": 0,
"device_desktop": 0,
"device_iphone": 1.0,
"device_ipad": 1.0,
"device_ipod": 0,
"device_android_smartphone": 1.0,
"device_android_tablet": 0,
"age_Unknown_gender_male": 0,
"age_Unknown_gender_female": 0,
"age_Unknown_gender_unknown": 0
},
"checkin_breakdown": {
"age_18-24_gender_male": 0,
"age_18-24_gender_female": 0,
"age_25-34_gender_male": 0,
"age_25-34_gender_female": 0,
"age_35-44_gender_male": 0,
"age_35-44_gender_female": 0,
"age_45-54_gender_male": 0,
"age_45-54_gender_female": 0,
"age_55-64_gender_male": 0,
"age_55-64_gender_female": 0,
"age_65+_gender_male": 0,
"age_65+_gender_female": 0,
"age_13-17_gender_male": 0,
"age_13-17_gender_female": 0,
"age_18-24_gender_unknown": 0,
"age_25-34_gender_unknown": 0,
"age_35-44_gender_unknown": 0,
"age_45-54_gender_unknown": 0,
"age_55-64_gender_unknown": 0,
"age_65+_gender_unknown": 0,
"age_13-17_gender_unknown": 0,
"device_other": 0,
"device_desktop": 0,
"device_iphone": 0,
"device_ipad": 0,
"device_ipod": 0,
"device_android_smartphone": 0,
"device_android_tablet": 0,
"age_Unknown_gender_male": 0,
"age_Unknown_gender_female": 0,
"age_Unknown_gender_unknown": 0
},
"leadgen_other_breakdown": {
"age_18-24_gender_male": 0,
"age_18-24_gender_female": 0,
"age_25-34_gender_male": 0,
"age_25-34_gender_female": 0,
"age_35-44_gender_male": 0,
"age_35-44_gender_female": 0,
"age_45-54_gender_male": 0,
"age_45-54_gender_female": 0,
"age_55-64_gender_male": 0,
"age_55-64_gender_female": 0,
"age_65+_gender_male": 0,
"age_65+_gender_female": 0,
"age_13-17_gender_male": 0,
"age_13-17_gender_female": 0,
"age_18-24_gender_unknown": 0,
"age_25-34_gender_unknown": 0,
"age_35-44_gender_unknown": 0,
"age_45-54_gender_unknown": 0,
"age_55-64_gender_unknown": 0,
"age_65+_gender_unknown": 0,
"age_13-17_gender_unknown": 0,
"device_other": 0,
"device_desktop": 0,
"device_iphone": 0,
"device_ipad": 0,
"device_ipod": 0,
"device_android_smartphone": 0,
"device_android_tablet": 0,
"age_Unknown_gender_male": 0,
"age_Unknown_gender_female": 0,
"age_Unknown_gender_unknown": 0
},
"leads": 19,
"impressions": 581347,
"call_to_action_clicks": 0,
"clicks": 1744,
"social_clicks": 0,
"reach": 550040.0,
"social_reach": 0,
"social_impressions": 0,
"website_clicks": 0,
"inline_link_clicks": 1100.0,
"link_click": 1100.0,
"page_engagement": 1130.0,
"like": 0,
"post_engagement": 1130.0,
"comment": 1.0,
"post": 5.0,
"post_reaction": 24.0,
"checkin": 0,
"action_reaction": 0,
"leadgen.other": 0,
"spend": 4546.13,
"video_p100_watched_actions": 0,
"offline_conversion_purchases": 7,
"offline_conversion_purchases_value": 82,
"cpc": 2.61,
"cpm": 7.82,
"ctr": 0.3,
"cpsc": 3.57,
"roas": 328,
"average_daily_reach": 2217.9
},
"totals_per_interval": [
{
"start_date": "2020-10-10",
"impressions": 1403,
"call_to_action_clicks": 5,
"clicks": 16,
"social_clicks": 10,
"reach": 1403,
"social_reach": 70,
"social_impressions": 1403,
"website_clicks": 8,
"inline_link_clicks": 5,
"link_click": 9,
"page_engagement": 77,
"like": 85,
"post_engagement": 84,
"comment": 8,
"post": 9,
"post_reaction": 65,
"checkin": 8,
"action_reaction": 9,
"leadgen.other": 0,
"spend": 25,
"video_p100_watched_actions": 20,
"video_avg_percent_watched_actions": 76,
"offline_conversion_purchases": 7,
"offline_conversion_purchases_value": 82,
"leads": 18,
"cpc": 1.56,
"cpm": 17.82,
"ctr": 1.14,
"cpsc": 3.57,
"roas": 328
}
]
},
"global_master_advertiser_id": "TEST_1"
}
| Field Name | Datatype | Description |
|---|---|---|
| report_type | String | Name of the API |
| report_date | String | Date report was run |
| earliest_date_available | String | Earliest Data is Available |
| start_date | String | Start date of report |
| end_date | String | End date of report |
| time_zone | String | Time Zone |
| interval_size | String | Interval Size ('none', 'day', 'calendar_week' or 'calendar_month') |
| currency | String | Currency Type of Monetary Values Returned in Report (Example: USD, AUD, CAD) |
| report_data | Object | Report details |
Report Data Object
| Field Name | Datatype | Description |
|---|---|---|
| campaigns | Object | Data for specified campaign |
| totals | Object | Data for Overall Totals |
| totals_per_interval | Object | Overall Totals Broken Down by Interval |
Campaigns Object
| Field Name | Datatype | Nullable | Description |
|---|---|---|---|
| name | String | No | Campaign Name |
| global_master_campaign_id | String | No | Unique Identifier for Campaign |
| start_date | String | No | Campaign Start Date |
| end_date | String | Yes | Campaign End Date |
| type | String | No | Type of Campaign |
| status | String | No | Status of Campaign |
| goals | Array | No | Array of Goals |
| cycles | Cycle[] | No | Array of Cycle |
| intervals | Interval[] | No | Array of Interval |
Goal Object
| Field Name | Datatype | Nullable | Description |
|---|---|---|---|
| name | String | No | Campaign Name |
| goal_type_id | Int | No | Goal Unique Identifier |
| goal_type | String | No | Goal Type Name |
Cycles Object
| Field Name | Datatype | Nullable | Description |
|---|---|---|---|
| campaign_cycle | String | No | Unique Identifier for Cycle |
| start_date | String | No | Cycle Start Date |
| end_date | String | Yes | Cycle End Date |
| intervals | Interval[] | No | Array of Interval |
Intervals Object
| Field Name | Datatype | Nullable | Description |
|---|---|---|---|
| start_date | String | No | Start Date for Interval |
| impressions | Int | No | Total Impressions for Interval |
| call_to_action_clicks | Int | No | Total Call to Action Clicks for Interval |
| clicks | Int | No | Total Clicks for Interval |
| social_clicks | Int | No | Total Social Clicks for Interval |
| reach | Int | No | Total Reach for Interval |
| social_reach | Int | No | Total Social Reach for Interval |
| social_impressions | Int | No | Total Social Impressions for Interval |
| website_clicks | Int | No | Total Website Clicks for Interval |
| inline_link_clicks | Int | No | Total Inline Link Clicks for Interval |
| link_click | Int | No | Total Link Clicks for Interval |
| page_engagement | Int | No | Total Page Engagement for Interval |
| like | Int | No | Total Likes for Interval |
| post_engagement | Int | No | Total Post Engagement for Interval |
| comment | Int | No | Total Comments for Interval |
| post | Int | No | Total Posts for Interval |
| post_reaction | Int | No | Total Post Reactions for Interval |
| checkin | Int | No | Total Checkins for Interval |
| action_reaction | Int | No | Total Action Reaction for Interval |
| leadgen.other | Int | No | Total leadgen.other for Interval |
| frequency | Int | No | Average. This metric is available only for param interval_size is day |
| spend | Int | No | Total Spend for Interval |
| video_p100_watched_actions | Int | No | Total Videos Watched to 100 percent for Interval |
| offline_conversion_purchases | Int | No | Total Offline Conversion Purchases for Interval |
| offline_conversion_purchases_value | Int | No | Total Offline Conversion Purchase Value for Interval |
| omni_purchase_actions | Int | No | Purchases Value for Interval |
| omni_purchase_purchase_roas | Int | No | Purchase ROAS for Interval |
| omni_purchase_action_values | Int | No | Purchase Conversion Value for Interval |
| cpc | Int | No | Total Cost per Click for Interval |
| cpm | Int | No | Total Cost per Milli for Interval |
| ctr | Int | No | Total Click Through Rate for Interval |
| cpsc | Int | No | Total CPSC for Interval |
| roas | Int | No | Total ROAS for Interval |
Totals Object
| Field Name | Datatype | Nullable | Description |
|---|---|---|---|
| impressions | Int | No | Total Impressions |
| call_to_action_clicks | Int | No | Total Call to Action Clicks |
| clicks | Int | No | Total Clicks |
| social_clicks | Int | No | Total Social Clicks |
| reach | Int | No | Total Reach |
| social_reach | Int | No | Total |
| social_impressions | Int | No | Total Social Impressions |
| website_clicks | Int | No | Total Website Clicks |
| inline_link_clicks | Int | No | Total Inline Link Clicksl |
| link_click | Int | No | Total Link Clicks |
| page_engagement | Int | No | Total Page Engagement |
| like | Int | No | Total Likes |
| post_engagement | Int | No | Total Post Engagement |
| comment | Int | No | Total Comments |
| post | Int | No | Total Posts |
| post_reaction | Int | No | Total Post Reactions |
| checkin | Int | No | Total Checkins |
| action_reaction | Int | No | Total Action Reaction |
| leadgen.other | Int | No | Total leadgen.other |
| spend | Int | No | Total Spend |
| video_p100_watched_actions | Int | No | Total Videos Watched to 100 percent |
| offline_conversion_purchases | Int | No | Total Offline Conversion Purchases |
| offline_conversion_purchases_value | Int | No | Total Offline Conversion Purchase Value |
| omni_purchase_actions | Int | No | Total Purchases Value |
| omni_purchase_purchase_roas | Int | No | Total Purchase ROAS |
| omni_purchase_action_values | Int | No | Total Purchase Conversion Value |
| cpc | Int | No | Total Cost per Click |
| cpm | Int | No | Total Cost per Milli |
| ctr | Int | No | Total Click Through Rate |
| cpsc | Int | No | Total CPSC |
| roas | Int | No | Total ROAS |
| reach_breakdown | Breakdown[] | No | Reach breakdowns |
| impressions_breakdown | Breakdown[] | No | Impressions breakdowns |
| clicks_breakdown | Breakdown[] | No | Clicks breakdowns |
Breakdown Object
| Field Name | Datatype | Nullable | Description |
|---|---|---|---|
| age_18-24_gender_male | Int | No | Breakdowns for Males Age 18-24 |
| age_18-24_gender_female | Int | No | Breakdowns for Females Age 18-24 |
| age_25-34_gender_male | Int | No | Breakdowns for Males Age 25-34 |
| age_25-34_gender_female | Int | No | Breakdowns for Females Age 25-34 |
| age_35-44_gender_male | Int | No | Breakdowns for Males Age 35-44 |
| age_35-44_gender_female | Int | No | Breakdowns for Females Age 35-44 |
| age_45-54_gender_male | Int | No | Breakdowns for Males Age 45-54 |
| age_45-54_gender_female | Int | No | Breakdowns for Females Age 45-54 |
| age_55-64_gender_male | Int | No | Breakdowns for Males Age 55-64 |
| age_55-64_gender_female | Int | No | Breakdowns for Females Age 55-64 |
| age_65+_gender_male | Int | No | Breakdowns for Males Age 65+ |
| age_65+_gender_female | Int | No | Breakdowns for Females Age 65+ |
| age_13-17_gender_male | Int | No | Breakdowns for Males Age 13-17 |
| age_13-17_gender_female | Int | No | Breakdowns for Females Age 13-17 |
| age_18-24_gender_unknown | Int | No | Breakdowns for Males Age 18-24 |
| age_25-34_gender_unknown | Int | No | Breakdowns for Unknown Gender Age 25-34 |
| age_35-44_gender_unknown | Int | No | Breakdowns for Unknown Gender Age 18-24 |
| age_45-54_gender_unknown | Int | No | Breakdowns for Unknown Gender Age 45-54 |
| age_55-64_gender_unknown | Int | No | Breakdowns for Unknown Gender Age 55-64 |
| age_65+_gender_unknown | Int | No | Breakdowns for Unknown Gender Age 65+ |
| age_13-17_gender_unknown | Int | No | Breakdowns for Unknown Gender Age 13-17 |
| device_other | Int | No | Breakdowns for Device Other |
| device_desktop | Int | No | Breakdowns for Device Desktop |
| device_iphone | Int | No | Breakdowns for Device iPhone |
| device_ipad | Int | No | Breakdowns for Device iPad |
| device_ipod | Int | No | Breakdowns for Device iPod |
| device_android_smartphone | Int | No | Breakdowns for Device Android Smartphone |
| device_android_tablet | Int | No | Breakdowns for Device Android Tablet |
| age_Unknown_gender_male | Int | No | Breakdowns for Males Age Unknown |
| age_Unknown_gender_female | Int | No | Breakdowns for Femails Age Unknown |
| age_Unknown_gender_unknown | Int | No | Breakdowns for Unknown Gender Age Unknown |
Totals Per Interval Object
This is an Interval object across all campaigns.
YouTube Campaign Metrics
Resource Overview
| Method | URI Format |
|---|---|
| GET | /client_reports/youtube/[gmaid]?[query_params] |
Use GET to retrieve information for the YouTube report for a given advertiser.
The data returned will include impressions, views, clicks, view-through rate, click-through rate, cost per view, and eCPM organized by campaign, and also broken out by age, gender, and device type.
Parameters
When using the GET method, the results can be filtered using these parameters:
| Param | Function |
|---|---|
| start_date | Restricts the results to those occurring on or after this date |
| end_date | Restricts the results to those occurring on or before this date |
| global_master_campaign_id[] | Restrict results to one or more specific campaigns. This should be a comma separated string. Ex: global_master_campaign_id[]=TEST_1,TEST_2 |
| campaign_status[] | Restrict results to all campaigns with given status values. Allowed values are running, stopped and ended. This should be a comma separated string. Ex: campaign_status[]=running,stopped |
| campaign_cycle | Restrict results to a single campaign cycle |
| interval_size | Use calendar_month or calendar_week to roll up the data points into calendar intervals (default is 1 day per interval) |
To specify a date range:
- Specify start_date and end_date.
- When specifying a campaign_cycle, do not use date range params.
Response Data Details
Retrieve data for a specific range of dates
curl -H "Authorization: Bearer OAUTH_ACCESS_TOKEN" \
https://api.localiqservices.com/client_reports/youtube/TEST_1?start_date=2016-12-01&end_date=2016-12-31
Retrieve data for a specific campaign starting on a certain date
curl -g -H "Authorization: Bearer OAUTH_ACCESS_TOKEN \
https://api.localiqservices.com/client_reports/youtube/TEST_1?global_master_campaign_id[]=TEST_1&start_date=2016-10-01&end_date=2016-12-31
Retrieve data for a specific campaign cycle
curl -H "Authorization: Bearer OAUTH_ACCESS_TOKEN" \
https://api.localiqservices.com/client_reports/youtube/TEST_1?campaign_cycle=TEST_1
Retrieve data for campaigns that are stopped and running
curl -g -H "Authorization: Bearer OAUTH_ACCESS_TOKEN" \
https://api.localiqservices.com/client_reports/youtube/TEST_1?&campaign_status[]=running,stopped&start_date=2016-10-01&end_date=2016-12-31
Example Response
{
"report_type": "youtube",
"report_date": "2020-10-16",
"earliest_date_available": "2020-01-01",
"start_date": "2020-10-10",
"end_date": "2020-10-10",
"time_zone": "America/Los_Angeles",
"interval_size": "day",
"currency": "USD",
"global_master_advertiser_id": "TEST_1",
"report_data": {
"campaigns": [
{
"name": "Youtube Campaign (Demo)",
"global_master_campaign_id": "TEST_691223",
"start_date": "2020-01-01",
"end_date": null,
"type": "display",
"status": "running",
"intervals": [
{
"start_date": "2020-10-10",
"impressions": 1241,
"views": 21,
"clicks": 17,
"video_played_to_25_pct": 42,
"video_played_to_50_pct": 35,
"video_played_to_75_pct": 28,
"video_played_to_100_pct": 21,
"spend": 25,
"vtr": 1.69,
"ctr": 1.37,
"cpv": 1.19,
"eCPM": 20.15
}
]
},
{
"name": "Xmedia Campaign (Demo)",
"global_master_campaign_id": "TEST_691233",
"start_date": "2020-01-01",
"end_date": null,
"type": "xmedia",
"status": "running",
"intervals": [
{
"start_date": "2020-10-10",
"impressions": 248,
"views": 21,
"clicks": 3,
"video_played_to_25_pct": 42,
"video_played_to_50_pct": 35,
"video_played_to_75_pct": 28,
"video_played_to_100_pct": 21,
"spend": 25,
"vtr": 8.47,
"ctr": 1.21,
"cpv": 1.19,
"eCPM": 100.81
}
]
}
],
"impression_breakdowns": {
"age_breakdowns": {
"age_18_24": 212,
"age_25_34": 212,
"age_35_44": 212,
"age_45_54": 212,
"age_55_64": 212,
"age_65_up": 212,
"unknown": 212
},
"gender_breakdowns": {
"female": {
"total": 495,
"percent": 33.33
},
"male": {
"total": 495,
"percent": 33.33
},
"undetermined": {
"total": 495,
"percent": 33.33
}
},
"device_breakdowns": {
"connected_tv": {
"total": 297,
"percent": 20
},
"desktop": {
"total": 297,
"percent": 20
},
"mobile": {
"total": 297,
"percent": 20
},
"tablet": {
"total": 297,
"percent": 20
},
"unknown": {
"total": 297,
"percent": 20
}
}
},
"view_breakdowns": {
"age_breakdowns": {
"age_18_24": 6,
"age_25_34": 6,
"age_35_44": 6,
"age_45_54": 6,
"age_55_64": 6,
"age_65_up": 6,
"unknown": 6
},
"gender_breakdowns": {
"female": {
"total": 6,
"percent": 33.33
},
"male": {
"total": 6,
"percent": 33.33
},
"undetermined": {
"total": 6,
"percent": 33.33
}
},
"device_breakdowns": {
"connected_tv": {
"total": 6,
"percent": 20
},
"desktop": {
"total": 6,
"percent": 20
},
"mobile": {
"total": 6,
"percent": 20
},
"tablet": {
"total": 6,
"percent": 20
},
"unknown": {
"total": 6,
"percent": 20
}
}
},
"click_breakdowns": {
"age_breakdowns": {
"age_18_24": 2,
"age_25_34": 2,
"age_35_44": 2,
"age_45_54": 2,
"age_55_64": 2,
"age_65_up": 2,
"unknown": 2
},
"gender_breakdowns": {
"female": {
"total": 6,
"percent": 33.33
},
"male": {
"total": 6,
"percent": 33.33
},
"undetermined": {
"total": 6,
"percent": 33.33
}
},
"device_breakdowns": {
"connected_tv": {
"total": 3,
"percent": 20
},
"desktop": {
"total": 3,
"percent": 20
},
"mobile": {
"total": 3,
"percent": 20
},
"tablet": {
"total": 3,
"percent": 20
},
"unknown": {
"total": 3,
"percent": 20
}
}
},
"totals": {
"impressions": 1489,
"views": 42,
"clicks": 20,
"video_played_to_25_pct": 42,
"video_played_to_50_pct": 35,
"video_played_to_75_pct": 28,
"video_played_to_100_pct": 21,
"spend": 50,
"vtr": 2.82,
"ctr": 1.34,
"cpv": 1.19,
"eCPM": 33.58
},
"totals_per_interval": [
{
"start_date": "2020-10-10",
"impressions": 1489,
"views": 42,
"clicks": 20,
"video_played_to_25_pct": 42,
"video_played_to_50_pct": 35,
"video_played_to_75_pct": 28,
"video_played_to_100_pct": 21,
"spend": 50,
"vtr": 2.82,
"ctr": 1.34,
"cpv": 1.19,
"eCPM": 33.58
}
]
}
}
| Field Name | Datatype | Description |
|---|---|---|
| report_type | String | Name of the API |
| report_date | String | Date report was run |
| earliest_date_available | String | Earliest Data is Available |
| start_date | String | Start date of report |
| end_date | String | End date of report |
| time_zone | String | Time Zone |
| interval_size | String | Interval Size ('none', 'day', 'calendar_week' or 'calendar_month') |
| currency | String | Currency Type of Monetary Values Returned in Report (Example: USD, AUD, CAD) |
| report_data | Object | Report details |
Report Data Object
| Field Name | Datatype | Description |
|---|---|---|
| campaigns | Object | Data for specified campaign |
| impression_breakdowns | ImpressionBreakdown | ImpressionBreakdown |
| view_breakdowns | ViewBreakdown | ViewBreakdown |
| click_breakdowns | ClickBreakdown | ClickBreakdown |
| totals | Object | Data for Overall Totals |
| totals_per_interval | Object | Overall Totals Broken Down by Interval |
Campaigns Object
| Field Name | Datatype | Nullable | Description |
|---|---|---|---|
| name | String | No | Campaign Name |
| global_master_campaign_id | String | No | Unique Identifier for Campaign |
| start_date | String | No | Campaign Start Date |
| end_date | String | Yes | Campaign End Date |
| type | String | No | Type of Campaign |
| status | String | No | Type of Campaign |
| intervals | Interval[] | No | Array of Interval |
Intervals Object
| Field Name | Datatype | Nullable | Description |
|---|---|---|---|
| start_date | String | No | Start Date for Interval |
| impressions | Int | No | Impressions for Interval |
| views | Int | No | Views for Interval |
| clicks | Int | No | Clicks for Interval |
| video_played_to_25_pct | Int | No | Number of Videos played to 25% |
| video_played_to_50_pct | Int | No | Number of Videos played to 50% |
| video_played_to_75_pct | Int | No | Number of Videos played to 75% |
| video_played_to_100_pct | Int | No | Number of Videos played to 100% |
| vtr | Float | No | View through Rate |
| ctr | Float | No | Click through Rate |
| eCPM | Float | No | Effective Cost per Thousand Impressions |
ImpressionBreakdown Object
| Field Name | Datatype | Nullable | Description |
|---|---|---|---|
| age_breakdowns | AgeBreakdown | No | AgeBreakdown Object |
| gender_breakdowns | GenderBreakdown | No | GenderBreakdown Object |
| device_breakdowns | DeviceBreakdown | No | DeviceBreakdown Object |
ViewBreakdown Object
| Field Name | Datatype | Nullable | Description |
|---|---|---|---|
| age_breakdowns | AgeBreakdown | No | AgeBreakdown Object |
| gender_breakdowns | GenderBreakdown | No | GenderBreakdown Object |
| device_breakdowns | DeviceBreakdown | No | DeviceBreakdown Object |
ClickBreakdown Object
| Field Name | Datatype | Nullable | Description |
|---|---|---|---|
| age_breakdowns | AgeBreakdown | No | AgeBreakdown Object |
| gender_breakdowns | GenderBreakdown | No | GenderBreakdown Object |
| device_breakdowns | DeviceBreakdown | No | DeviceBreakdown Object |
AgeBreakdown Object
| Field Name | Datatype | Nullable | Description |
|---|---|---|---|
| age_18_24 | Int | No | Count for Age 18-24 |
| age_25_34 | Int | No | Count for Age 25-44 |
| age_35_44 | Int | No | Count for Age 35-44 |
| age_45_54 | Int | No | Count for Age 45-54 |
| age_55_64 | Int | No | Count for Age 55-64 |
| age_65_up | Int | No | Count for Age 65+ |
| unknown | Int | No | Count for Age unknown |
GenderBreakdown Object
| Field Name | Datatype | Nullable | Description |
|---|---|---|---|
| female | Female | No | Female Object |
| male | Male | No | Male Object |
| undetermined | Undetermined | No | Undetermined Object |
Female/Male/Undetermined Object
| Field Name | Datatype | Nullable | Description |
|---|---|---|---|
| total | Int | No | Count |
| percent | Int | No | Percent of Total Count |
DeviceBreakdown Object
| Field Name | Datatype | Nullable | Description |
|---|---|---|---|
| connected_tv | ConnectedTv | No | ConnectedTv Object |
| desktop | Desktop | No | Desktop Object |
| mobile | Mobile | No | Mobile Object |
| tablet | Tablet | No | Tablet Object |
| unknown | Unknown | No | Unknown Object |
ConnectedTv/Desktop/Mobile/Tablet/Unknown Object
| Field Name | Datatype | Nullable | Description |
|---|---|---|---|
| total | Int | No | Count |
| percent | Int | No | Percent of Total Count |
Totals Object
| Field Name | Datatype | Nullable | Description |
|---|---|---|---|
| impressions | Int | No | Total Impressions |
| views | Int | No | Total Views |
| clicks | Int | No | Total Clicks |
| video_played_to_25_pct | Int | No | Total Number of Videos played to 25% |
| video_played_to_50_pct | Int | No | Total Number of Videos played to 50% |
| video_played_to_75_pct | Int | No | Total Number of Videos played to 75% |
| video_played_to_100_pct | Int | No | Total Number of Videos played to 100% |
| vtr | Float | No | Total View through Rate |
| ctr | Float | No | Total Click through Rate |
| eCPM | Float | No | Total Effective Cost per Thousand Impressions |
Totals Per Interval Object
This is an Interval object across all campaigns.
Traffic Metric APIs
Top Referrer
Describes the distribution of referrers for an advertiser for a given time period as well as attributing the source of the referral. This API endpoint is the data source for the Traffic Detail Report report in client center.
Resource Overview
| Method | URI Format |
|---|---|
| GET | /client_reports/top_referrer/[gmaid]?[query_params] |
Parameters
When using the GET method, the results can be filtered using these parameters:
| Param | Required | Function |
|---|---|---|
| start_date | Yes | Restricts the results to those occurring on or after this date and time. |
| end_date | Yes | Restricts the results to those occurring on or before this date and time. |
Response Data Details
curl --request GET \
--url 'https://api.localiqservices.com/client_reports/top_referrer/TEST_1??start_date=2016-12-01&end_date=2016-12-31' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer OAUTH_ACCESS_TOKEN'
Example Response
{
"api_name": "top_referrer",
"api_run_date": "2022-11-17",
"start_date": "2022-11-10",
"end_date": "2022-11-15",
"time_zone": "America/Los_Angeles",
"global_master_advertiser_id": "TEST_1",
"report_data": {
"sources": [
{
"name": "DIRECT",
"master_campaign_id": 1,
"is_paid": true,
"top_referrers": [
{
"referrer_host": "facebook.com",
"count": 5
}
]
},
{
"name": "DIRECT",
"master_campaign_id": 1,
"is_paid": true,
"top_referrers": [
{
"referrer_host": "fifa.com",
"count": 14
}
]
},
{
"name": "SEARCH",
"master_campaign_id": 1,
"is_paid": true,
"top_referrers": [
{
"referrer_host": "google.com",
"count": 14
}
]
},
{
"name": "SEARCH",
"master_campaign_id": -1,
"is_paid": false,
"top_referrers": [
{
"referrer_host": "fifa.com",
"count": 3
}
]
},
{
"name": "SOCIAL",
"master_campaign_id": -1,
"is_paid": false,
"top_referrers": [
{
"referrer_host": "fifa.com",
"count": 3
}
]
},
{
"name": "DIRECT",
"master_campaign_id": -1,
"is_paid": false,
"top_referrers": [
{
"referrer_host": "fifa.com",
"count": 13
}
]
},
{
"name": "OTHER",
"master_campaign_id": -1,
"is_paid": false,
"top_referrers": [
{
"referrer_host": "fifa.com",
"count": 9
}
]
}
]
}
}
The main body of the API response is found in the report_data object.
Base Object
| Field Name | Datatype | Description |
|---|---|---|
| api_name | String | Name of the API |
| api_run_date | String | Date report was run |
| start_date | String | Start date of report |
| end_date | String | End date of report |
| time_zone | String | Time Zone |
| report_data | Report Data Object | Report details |
| Field Name | Datatype | Nullable | Description |
|---|---|---|---|
| sources | Array | Yes | An array of source objects |
| Field Name | Datatype | Nullable | Description |
|---|---|---|---|
| name | String | Yes | The type of campaign SEARCH, OTHER, DIRECT |
| master_campaign_id | String | Yes | The master campaign id |
| is_paid | boolean | No | Is the campaign a paid campaign |
| top_referrers | Array | No | An array of top referrer objects |
| Field Name | Datatype | Nullable | Description |
|---|---|---|---|
| referrer_host | String | No | The hostname |
| count | Integer | No | The count of referrals from the specified host |
TotalTrack
Resource Overview
| Method | URI Format |
|---|---|
| GET | /client_reports/total_track/[gmaid]?[query_params] |
Use GET to retrieve information for the TotalTrack report for a given advertiser.
The data returned will include leads, clicks, calls, web_events and email values organized by campaign and campaign_cycle.
Parameters
When using the GET method, the results can be filtered using these parameters:
| Param | Function |
|---|---|
| start_date | Restricts the results to those occurring on or after this date |
| end_date | Restricts the results to those occurring on or before this date |
| global_master_campaign_id[] | Restrict results to one or more specific campaigns. This should be a comma separated string. Ex: global_master_campaign_id[]=TEST_1,TEST_2 |
| campaign_status[] | Restrict results to all campaigns with given status values. Allowed values are running, stopped and ended. This should be a comma separated string. Ex: campaign_status[]=running,stopped |
| campaign_types[] | Restrict results to campaigns of given type. Valid types: totaltrack_web, totaltrack_phone, totaltrack_web_phone |
| campaign_cycle | Restrict results to a single campaign cycle |
| interval_size | Use calendar_month or calendar_week to roll up the data points into calendar intervals (default is 1 day per interval) |
| include_cycles | Set to true or false on whether to include cycle nesting. Default value is false |
To specify a date range:
- Specify start_date and end_date.
- When specifying a
campaign_cycle, do not use date range params.
Response Data Details
Retrieve data for a specific range of dates
curl -H "Authorization: Bearer Bearer OAUTH_ACCESS_TOKEN" \
https://api.localiqservices.com/client_reports/total_track/TEST_1?start_date=2016-12-01&end_date=2016-12-31
Retrieve data for a specific campaign starting on a certain date
curl -g -H "Authorization: Bearer Bearer OAUTH_ACCESS_TOKEN" \
https://api.localiqservices.com/client_reports/total_track/TEST_1?global_master_campaign_id[]=TEST_1&start_date=2016-10-01&end_date=2016-12-31
Retrieve data for a specific campaign cycle
curl -H "Authorization: Bearer Bearer OAUTH_ACCESS_TOKEN" \
https://api.localiqservices.com/client_reports/total_track/TEST_1?campaign_cycle=TEST_1
Retrieve data for campaigns that are stopped and running
curl -g -H "Authorization: Bearer Bearer OAUTH_ACCESS_TOKEN" \
https://api.localiqservices.com/client_reports/total_track/TEST_1?&campaign_status[]=running,stopped&start_date=2016-10-01&end_date=2016-12-31
Retrieve data for a specific campaign starting on a certain date with cycle nesting
curl -g -H "Authorization: Bearer Bearer OAUTH_ACCESS_TOKEN" \
https://api.localiqservices.com/client_reports/total_track/TEST_1?global_master_campaign_id[]=TEST_1&start_date=2016-10-01&end_date=2016-12-31&include_cycles=true
Example Response
{
"totaltrack_type": "totaltrack_web_phone",
"report_type": "total_track",
"report_date": "2020-10-16",
"earliest_date_available": "2020-01-01",
"start_date": "2020-10-10",
"end_date": "2020-10-10",
"time_zone": "America/Los_Angeles",
"interval_size": "day",
"currency": "USD",
"report_data": {
"campaigns": [
{
"name": "Totaltrack Phone Campaign (Demo)",
"global_master_campaign_id": "TEST_691183",
"start_date": "2020-01-01",
"end_date": null,
"type": "totaltrack",
"status": "running",
"cycles": [
{
"campaign_cycle": "TEST_719047",
"start_date": "2020-10-07",
"end_date": null,
"intervals": [
{
"start_date": "2020-10-10",
"leads": 28,
"clicks": 10,
"calls": 10,
"web_events": 9,
"emails": 9,
"chats": 10
}
]
}
]
},
{
"name": "Totaltrack Web Phone Campaign (Demo)",
"global_master_campaign_id": "TEST_691187",
"start_date": "2020-01-01",
"end_date": null,
"type": "totaltrack",
"status": "running",
"cycles": [
{
"campaign_cycle": "TEST_719092",
"start_date": "2020-10-07",
"end_date": null,
"intervals": [
{
"start_date": "2020-10-10",
"leads": 23,
"clicks": 10,
"calls": 6,
"web_events": 7,
"emails": 10,
"chats": 11
}
]
}
]
},
{
"name": "Totaltrack Web Campaign (Demo)",
"global_master_campaign_id": "TEST_691190",
"start_date": "2020-01-01",
"end_date": null,
"type": "totaltrack",
"status": "running",
"cycles": [
{
"campaign_cycle": "TEST_719136",
"start_date": "2020-10-07",
"end_date": null,
"intervals": [
{
"start_date": "2020-10-10",
"leads": 23,
"clicks": 14,
"calls": 5,
"web_events": 9,
"emails": 9,
"chats": 12
}
]
}
]
}
],
"totals": {
"clicks": 34,
"calls": 21,
"web_events": 25,
"emails": 28,
"leads": 74,
"chats": 33
},
"totals_per_interval": [
{
"start_date": "2020-10-10",
"leads": 74,
"clicks": 34,
"calls": 21,
"web_events": 25,
"emails": 28,
"chats": 33
}
]
},
"global_master_advertiser_id": "TEST_1"
}
| Field Name | Datatype | Description |
|---|---|---|
| totaltrack_type | String | Indicates if Response is for web only, phone only, or both web and phone (totaltrack_web, totaltrack_phone, totaltrack_web_phone) |
| report_type | String | Name of the API |
| report_date | String | Date report was run |
| earliest_date_available | String | Earliest Data is Available |
| start_date | String | Start date of report |
| end_date | String | End date of report |
| time_zone | String | Time Zone |
| interval_size | String | Interval Size ('none', 'day', 'calendar_week' or 'calendar_month') |
| currency | String | Currency Type of Monetary Values Returned in Report (Example: USD, AUD, CAD) |
| report_data | Object | Report details |
| global_master_advertiser_id | String | Identifier for advertiser |
Report Data Object
| Field Name | Datatype | Description |
|---|---|---|
| campaigns | Object | Data for specified campaign |
| totals | Object | Data for Overall Totals |
| totals_per_interval | Object | Overall Totals Broken Down by Interval |
Campaigns Object
| Field Name | Datatype | Nullable | Description |
|---|---|---|---|
| name | String | No | Campaign Name |
| global_master_campaign_id | String | No | Unique Identifier for Campaign |
| start_date | String | No | Campaign Start Date |
| end_date | String | Yes | Campaign End Date |
| type | String | No | Type of Campaign |
| status | String | No | Status of Campaign |
| cycles | Cycle[] | No | Array of Cycle |
| intervals | Interval[] | No | Array of Interval |
Cycles Object
| Field Name | Datatype | Nullable | Description |
|---|---|---|---|
| campaign_cycle | String | No | Unique Identifier for Cycle |
| start_date | String | No | Cycle Start Date |
| end_date | String | Yes | Cycle End Date |
| intervals | Interval[] | No | Array of Interval |
Intervals Object
| Field Name | Datatype | Nullable | Description |
|---|---|---|---|
| start_date | String | No | Start Date for Interval |
| leads | Int | No | Leads for Interval |
| clicks | Int | No | Clicks for Interval |
| calls | Int | No | Calls for Interval |
| web_events | Int | No | Web Events for Interval |
| emails | Int | No | Emails for Interval |
| chats | Int | No | Total chat generated by paid traffic for Interval |
Totals Object
| Field Name | Datatype | Nullable | Description |
|---|---|---|---|
| leads | Int | No | Total Leads |
| clicks | Int | No | Total Clicks |
| calls | Int | No | Total Calls |
| web_events | Int | No | Total Web Events |
| emails | Int | No | Total Emails |
| chats | Int | No | Total chat generated by paid traffic |
Totals Per Interval Object
This is an Interval object across all campaigns.
Web Event Metrics
Resource Overview
| Method | URI Format |
|---|---|
| GET | /client_reports/cvt_events/[gmaid]?[query_params] |
This is an API that can be used by customers who have indicated that certain pages or actions of specific importance will benefit the performance of campaigns through more informed and meaningful conversions. All metrics are reported against the CVT/Web Event.
Web Events fall under these categories: ‘Request’, ‘Submit’ and ’unknown”. * A 'Request' Web Event is usually informational, in some cases, it can have a post-click activity that can generate a lead. * A 'Submit' CVT/Web Event is lead-generating. Metrics tied to a 'Request' CVT/Web Event are considered 'non-qualified', whereas metrics tied to a 'Submit' CVT/Web Event are considered 'qualified'. * An 'Unknown’ Web Event is one where the URL & name are missing. This happens periodically when a campaign cycles and a visitor triggers the web event while our system is renewing the web events data for the new cycle. From a metrics perspective, the web event occurred but we don’t know which one was triggered.
Use GET to retrieve web event activity for all CVT/Web Events for a given gmaid.
The data returned will include CVT/Web Events from each campaign with web event name, web event url, and metrics for the interval requested.
Parameters
When using the GET method, the results can be filtered using these parameters:
| Param | Required | Function |
|---|---|---|
| start_date | Yes | Restricts the results to events occurring on or after this date |
| end_date | Yes | Restricts the results to events occurring on or before this date |
| global_master_campaign_id[] | No | Restricts results to all campaigns with given master campaign id |
| interval_size | No | Use calendar_month or calendar_week to roll up the data points into calendar intervals (default is 1 day per interval) |
| campaign_status[] | No | Restrict results to all campaigns with given status values. Allowed values are running, stopped or ended |
| campaign_types[] | No | Restricts results to campaigns of given type, valid types: search, display, other, totaltrack_web, totaltrack_phone, totaltrack_web_phone, chat, xmedia |
To specify a date range:
- Specify start_date and end_date.
Response Data Details
Retrieve data for a specific range of dates
curl -H "Authorization: Bearer OAUTH_ACCESS_TOKEN" \
https://api.localiqservices.com/client_reports/cvt_events/TEST_1?start_date=2019-10-01&end_date=2020-02-25'
Retrieve data for a specific master campaign id
curl -H "Authorization: Bearer OAUTH_ACCESS_TOKEN" \
https://api.localiqservices.com/client_reports/cvt_events/TEST_1?start_date=2019-10-01&end_date=2020-02-25&global_master_campaign_id[]=TEST_1' \
Retrieve data for a specific range of dates limited to ended campaigns
curl -H "Authorization: Bearer OAUTH_ACCESS_TOKEN" \
https://api.localiqservices.com/client_reports/cvt_events/TEST_1?start_date=2019-10-01&end_date=2020-02-25&campaign_status[]=ended' \
Retrieve data for a specific range of dates grouped by calendar week
curl -H "Authorization: Bearer OAUTH_ACCESS_TOKEN" \
https://api.localiqservices.com/client_reports/cvt_events/TEST_1?start_date=2019-10-01&end_date=2020-02-25&interval_size=calendar_week' \
Retrieve data with all options together with results below
curl -H "Authorization: Bearer OAUTH_ACCESS_TOKEN" \
https://api.localiqservices.com/client_reports/cvt_events/TEST_1?start_date=2019-10-01&end_date=2020-02-25&global_master_campaign_id[]=TEST_1&interval_size=calendar_week&campaign_status[]=running' \
Example Response
{
"report_type": "cvt_events",
"report_date": "2020-10-14",
"earliest_date_available": "2020-10-10",
"start_date": "2019-10-10",
"end_date": "2020-10-10",
"time_zone": "America/Los_Angeles",
"interval_size": "day",
"currency": "USD",
"report_data": {
"campaigns": [
{
"name": "Display Campaign (Demo)",
"global_master_campaign_id": "TEST_1",
"start_date": "2020-10-10",
"end_date": null,
"type": "display",
"status": "running",
"organization": "reachlocal",
"web_events": [
{
"web_event_name": "Form Submitted (Demo)",
"web_event_url": "www.rl-demo.com",
"cvt_type": "Submit",
"entry_type": 8,
"intervals": [
{
"date": "2020-10-10",
"qualified_web_events": 3,
"high_web_events": 3
}
]
}, {
"cvt_type": "Unknown",
"entry_type": 8,
"intervals": [
{
"date": "2020-10-10",
"qualified_web_events": 1,
"high_web_events": 1
}
]
},
{
"web_event_name": "Form Submitted (Demo)",
"web_event_url": "www.rl-demo.com",
"cvt_type": "Submit",
"entry_type": 7,
"intervals": [
{
"date": "2020-10-10",
"qualified_web_events": 3,
"high_web_events": 3
}
]
}
]
},
{
"name": "Search Campaign (Demo)",
"global_master_campaign_id": "TEST_4",
"start_date": "2020-10-10",
"end_date": null,
"type": "search",
"status": "running",
"organization": "reachlocal",
"web_events": [
{
"web_event_name": "Form Submitted (Demo)",
"web_event_url": "www.rl-demo.com",
"cvt_type": "Request",
"entry_type": 8,
"intervals": [
{
"date": "2020-10-10",
"qualified_web_events": 3,
"high_web_events": 0
}
]
},
{
"web_event_name": "Form Submitted (Demo)",
"web_event_url": "www.rl-demo.com",
"cvt_type": "Submit",
"entry_type": 7,
"intervals": [
{
"date": "2020-10-10",
"qualified_web_events": 6,
"high_web_events": 6
}
]
}
]
},
{
"name": "Totaltrack Web Phone Campaign (Demo)",
"global_master_campaign_id": "TEST_10",
"start_date": "2020-10-10",
"end_date": null,
"type": "totaltrack",
"status": "running",
"organization": "reachlocal",
"web_events": [
{
"web_event_name": "Form Submitted (Demo)",
"web_event_url": "www.rl-demo.com",
"cvt_type": "Request",
"entry_type": 8,
"intervals": [
{
"date": "2020-10-10",
"qualified_web_events": 6,
"high_web_events": 0
}
]
},
{
"web_event_name": "Form Submitted (Demo)",
"web_event_url": "www.rl-demo.com",
"cvt_type": "Request",
"entry_type": 7,
"intervals": [
{
"date": "2020-10-10",
"non_qualified_web_events": 3
}
]
}
]
},
{
"name": "Totaltrack Web Campaign (Demo)",
"global_master_campaign_id": "TEST_13",
"start_date": "2020-10-10",
"end_date": null,
"type": "totaltrack",
"status": "running",
"organization": "reachlocal",
"web_events": [
{
"web_event_name": "Form Submitted (Demo)",
"web_event_url": "www.rl-demo.com",
"cvt_type": "Request",
"entry_type": 7,
"intervals": [
{
"date": "2020-10-10",
"non_qualified_web_events": 4
}
]
},
{
"web_event_name": "Form Submitted (Demo)",
"web_event_url": "www.rl-demo.com",
"cvt_type": "Submit",
"entry_type": 8,
"intervals": [
{
"date": "2020-10-10",
"qualified_web_events": 3,
"high_web_events": 3
}
]
}
]
},
{
"name": "Other Campaign (Demo)",
"global_master_campaign_id": "TEST_16",
"start_date": "2020-10-10",
"end_date": null,
"type": "other",
"status": "running",
"organization": "reachlocal",
"web_events": [
{
"web_event_name": "Form Submitted (Demo)",
"web_event_url": "www.rl-demo.com",
"cvt_type": "Request",
"entry_type": 7,
"intervals": [
{
"date": "2020-10-10",
"non_qualified_web_events": 5
}
]
},
{
"web_event_name": "Form Submitted (Demo)",
"web_event_url": "www.rl-demo.com",
"cvt_type": "Request",
"entry_type": 8,
"intervals": [
{
"date": "2020-10-10",
"qualified_web_events": 2,
"high_web_events": 0
}
]
}
]
},
{
"name": "Chat Campaign (Demo)",
"global_master_campaign_id": "TEST_19",
"start_date": "2020-10-10",
"end_date": null,
"type": "chat",
"status": "running",
"organization": "reachlocal",
"web_events": [
{
"web_event_name": "Form Submitted (Demo)",
"web_event_url": "www.rl-demo.com",
"cvt_type": "Request",
"entry_type": 7,
"intervals": [
{
"date": "2020-10-10",
"non_qualified_web_events": 1
}
]
},
{
"web_event_name": "Form Submitted (Demo)",
"web_event_url": "www.rl-demo.com",
"cvt_type": "Submit",
"entry_type": 8,
"intervals": [
{
"date": "2020-10-10",
"qualified_web_events": 5,
"high_web_events": 5
}
]
}
]
},
{
"name": "Xmedia Campaign (Demo)",
"global_master_campaign_id": "TEST_34",
"start_date": "2020-10-10",
"end_date": null,
"type": "xmedia",
"status": "running",
"organization": "reachlocal",
"web_events": [
{
"web_event_name": "Form Submitted (Demo)",
"web_event_url": "www.rl-demo.com",
"cvt_type": "Submit",
"entry_type": 8,
"intervals": [
{
"date": "2020-10-10",
"qualified_web_events": 8,
"high_web_events": 8
}
]
},
{
"web_event_name": "Form Submitted (Demo)",
"web_event_url": "www.rl-demo.com",
"cvt_type": "Submit",
"entry_type": 7,
"intervals": [
{
"date": "2020-10-10",
"qualified_web_events": 2,
"high_web_events": 2
}
]
}
]
}
]
},
"global_master_advertiser_id": "TEST_1"
}
| Field Name | Datatype | Description |
|---|---|---|
| report_type | String | Report Type |
| report_date | String | Date Report was Run |
| earliest_date_available | String | Earliest Date Data is Available |
| start_date | String | Start Date of Report |
| end_date | String | End Date of Report |
| time_zone | String | Time Zone of Report |
| interval_size | String | Interval Size Report is Broken Into |
| currency | String | Currency Type of Monetary Values Returned in Report (Example: USD, AUD, CAD) |
| report_data | Object | Report Data Object |
| Field Name | Datatype | Description |
|---|---|---|
| campaigns | Object | Campaigns Object |
| global_master_advertiser_id | String | Global Master Advertiser ID |
| Field Name | Datatype | Description |
|---|---|---|
| name | String | Campaign name |
| global_master_campaign_id | String | Identifier for campaign |
| start_date | String | Start date for campaign |
| end_date | String | End date for campaign |
| type | String | Type of campaign |
| status | String | Current campaign status |
| organization | String | Organization |
| web_events | Object | Web Events Object |
| Field Name | Datatype | Description |
|---|---|---|
| web_event_name | String | Name of web event |
| web_event_url | String | Web event url |
| cvt_type | String | Request, Submit, or Unknown |
| entry_type | Integer | 7 (does not generate a lead event) or 8 (generates a lead event) |
| intervals | Object | Intervals Object |
| Field Name | Datatype | Description |
|---|---|---|
| date | String | Date for interval |
| non_qualified_web_events | Integer | A non-lead generating CVT/Web Event |
| qualified_web_events | Integer | A lead generating CVT/Web Event |
| high_web_events | Integer | A Request or Submit marked as high-value |
Cross Media Optimization (XMO)
XMO Metrics
Resource Overview
| Method | URI Format |
|---|---|
| GET | /client_reports/xmedia/[gmaid]?[query_params] |
Use GET to retrieve campaign performance metrics for the Cross Media Optimization (XMO) campaigns.
The data returned will include impressions, leads, clicks, calls, qualified_web_events, web_events, emails, chats and totals of the leads. Please note chats will be reported as 0 in this API. Please use the XMO channel metrics API to get the chat counts. The total leads are based on all web events.
Parameters
When using the GET method, the results can be filtered using these parameters:
| Param | Function |
|---|---|
start_date |
Restricts the results to those ocurring on or after this date. |
end_date |
Restricts the results to those ocurring on or before this date. |
global_master_campaign_id[] |
Restrict results to one or more specific campaigns. |
campaign_status[] |
Restrict results to all campaigns with given status values. Allowed values are running, stopped and ended |
campaign_types[] |
Default: xmedia (can be used to return other campaign types) |
campaign_cycle |
Restrict results to a single campaign cycle |
interval_size |
Use calendar_month or calendar_week to roll up the data points into calendar intervals (default is 1 day per interval) |
include_cycles |
Set to true or false on whether to include cycle nesting. Default value is false. |
Response Data Details
Retrieve data for a specific range of dates
curl -H "Authorization: Bearer OAUTH_ACCESS_TOKEN" \
"https://api.localiqservices.com/client_reports/xmedia/TEST_1?start_date=2020-03-10&end_date=2020-03-10"
Retrieve data for a specific range of dates
curl -H "Authorization: Bearer OAUTH_ACCESS_TOKEN" \
"https://api.localiqservices.com/client_reports/xmedia/TEST_1?start_date=2016-12-01&end_date=2016-12-31"
Retrieve data for a specific campaign starting on a certain date
curl -H "Authorization: Bearer OAUTH_ACCESS_TOKEN" \
"https://api.localiqservices.com/client_reports/xmedia/TEST_1?global_master_campaign_id[]=USA_14&start_date=2016-10-01&end_date=2016-12-31"
Retrieve data for a specific campaign cycle
curl -H "Authorization: Bearer OAUTH_ACCESS_TOKEN" \
"https://api.localiqservices.com/client_reports/xmedia/TEST_1?campaign_cycle=USA_100"
Retrieve data for campaigns that are stopped and running
curl -H "Authorization: Bearer OAUTH_ACCESS_TOKEN" \
"https://api.localiqservices.com/client_reports/xmedia/TEST_1?campaign_status[]=running&campaign_status[]=stopped&start_date=2016-10-01&end_date=2016-12-31"
Retrieve data for a specific campaign starting on a certain date with cycle nesting
curl -H "Authorization: Bearer OAUTH_ACCESS_TOKEN" \
"https://api.localiqservices.com/client_reports/xmedia/TEST_1?global_master_campaign_id[]=USA_14&start_date=2016-10-01&end_date=2016-12-31&include_cycles=true"
Example Response
{
"api_name": "xmedia",
"api_run_date": "2020-07-08",
"earliest_date_available": "2020-07-01",
"start_date": "2020-07-01",
"end_date": "2020-07-01",
"time_zone": "America/Los_Angeles",
"interval_size": "day",
"currency": "USD",
"global_master_advertiser_id": "TEST_1",
"advertiser_name": "Advertiser (Demo)",
"report_data": {
"campaigns": [
{
"name": "Xmedia Campaign (Demo)",
"global_master_campaign_id": "TEST_79936",
"organization": "reachlocal",
"start_date": "2020-07-01",
"end_date": null,
"type": "xmedia",
"status": "running",
"goals": [
{
"goal_type_id": 1,
"goal_type": "CPL"
},
{
"goal_type_id": 6,
"goal_type": "Contacts (Dynamic Ads - Automotive)"
}
],
"intervals": [
{
"start_date": "2020-07-01",
"impressions": 1184,
"clicks": 18,
"views": 18,
"calls": 9,
"web_events": 7,
"qualified_web_events": 3,
"emails": 9,
"chats": 0,
"leads": 25,
"spend": 25.0,
"ctr": 1.52,
"cpc": 1.39
}
]
}
],
"totals": {
"impressions": 1184.0,
"clicks": 18,
"views": 18,
"calls": 9,
"web_events": 7,
"qualified_web_events": 3,
"emails": 9,
"chats": 0,
"leads": 25,
"spend": 25.0,
"ctr": 1.52,
"cpc": 1.39
},
"totals_per_interval": [
{
"start_date": "2020-07-01",
"impressions": 1184,
"clicks": 18,
"views": 18,
"calls": 9,
"web_events": 7,
"qualified_web_events": 3,
"emails": 9,
"chats": 0,
"leads": 25,
"spend": 25.0,
"ctr": 1.52,
"cpc": 1.39
}
]
}
}
Campaigns
| Field Name | Datatype | Description |
|---|---|---|
| name | String | Campaign Name |
| global_master_campaign_id | String | Unique Identifier for Campaign |
| organization | String | Either reachlocal or gannett |
| start_date | String | Campaign Start Date |
| end_date | String | Campaign End Date |
| type | String | Type of Campaign |
| status | String | Status of Campaign |
Goals Array
| Field Name | Datatype | Description |
|---|---|---|
| goal_type_id | Int | goal type id |
| goal_type | String | goal type name |
Intervals Array
| Field Name | Datatype | Description |
|---|---|---|
| start_date | String | Campaign Start Date |
| impressions | Int | Total Impressions for Campaign |
| clicks | Float | Total Clicks for Interval |
| views | Float | Total Views for Interval |
| calls | Float | Total Calls for Interval |
| web_events | Int | Total Web Events for Interval |
| qualified_web_events | Int | Total lead-generating CVT/Web Events for Interval |
| emails | Float | Total Emails for Interval |
| chats | Float | Total chat generated by paid traffic for Interval |
| leads | Float | Total Leads for Campaign |
| spend | Float | Total Spend for Interval |
| ctr | Float | Click-through Rate for Interval |
| cpc | Float | Cost Per Click for Interval |
Totals Object
| Field Name | Datatype | Description |
|---|---|---|
| impressions | Int | Total Impressions |
| clicks | Float | Total Clicks |
| views | Float | Total Views |
| calls | Float | Total Calls |
| web_events | Int | Total Web Events |
| qualified_web_events | Int | Total lead-generating CVT/Web Events |
| emails | Float | Total Emails |
| chats | Float | Total chat generated by paid traffic |
| leads | Float | Total Leads |
| spend | Float | Total Spend |
| ctr | Float | Overall Click-through Rate |
| cpc | Float | Overall Cost Per Click |
Totals Per Interval Object
| Field Name | Datatype | Description |
|---|---|---|
| start_date | String | Start Date of interval |
| impressions | Int | Total Impressions for Campaign |
| clicks | Float | Total Clicks for Interval |
| views | Float | Total Views for Interval |
| calls | Float | Total Calls for Interval |
| web_events | Int | Total Web Events for Interval |
| qualified_web_events | Int | No |
| emails | Float | Total Emails for Interval |
| chats | Float | Total Chats for Interval |
| leads | Float | Total Leads for Campaign |
| spend | Float | Total Spend for Interval |
| ctr | Float | Click-through Rate for Interval |
| cpc | Float | Cost Per Click for Interval |
XMO Channel Metrics
Resource Overview
| Method | URI Format |
|---|---|
| GET | /client_reports/xmedia_channel/[gmaid]?[query_params] |
Use GET to retrieve campaign performance metrics by channel (search, social etc.) for the Cross Media Optimization (XMO) campaigns. This API can be used to see how each channel performed for an Xmedia Campaign.
Parameters
When using the GET method, the results can be filtered using these parameters:
| Param | Function |
|---|---|
start_date |
Restricts the results to those ocurring on or after this date |
end_date |
Restricts the results to those ocurring on or before this date |
global_master_campaign_id[] |
Restrict results to one or more specific campaigns |
campaign_status[] |
Restrict results to all campaigns with given status values. Allowed values are running, stopped and ended |
campaign_cycle |
Restrict results to a single campaign cycle |
interval_size |
Use calendar_month or calendar_week to roll up the data points into calendar intervals (default is 1 day per interval) |
include_cycles |
Set to true or false on whether to include cycle nesting. Default value is false |
channels[] |
Specifies which channels to filter results by. Valid channels are search, display, social, chat, video and other |
campaign_types[] |
Default: xmedia (can be used to return other campaign types) |
Response Data Details
Retrieve data for a specific range of dates
curl -H "Authorization: Bearer OAUTH_ACCESS_TOKEN" \
"https://api.localiqservices.com/client_reports/xmedia_channel/TEST_1?start_date=2020-03-10&end_date=2020-03-10"
Retrieve data for a specific range of dates
curl -H "Authorization: Bearer OAUTH_ACCESS_TOKEN" \ "https://api.localiqservices.com/client_reports/xmedia_channel/TEST_1?start_date=2016-12-01&end_date=2016-12-31"Retrieve data for a specific campaign starting on a certain datecurl -H "Authorization: Bearer OAUTH_ACCESS_TOKEN" \ "https://api.localiqservices.com/client_reports/xmedia_channel/TEST_1?global_master_campaign_id[]=USA_14&start_date=2016-10-01&end_date=2016-12-31"Retrieve data for a specific campaign cyclecurl -H "Authorization: Bearer OAUTH_ACCESS_TOKEN" \ "https://api.localiqservices.com/client_reports/xmedia_channel/TEST_1?campaign_cycle=USA_100"Retrieve data for campaigns that are stopped and runningcurl -H "Authorization: Bearer OAUTH_ACCESS_TOKEN" \ "https://api.localiqservices.com/client_reports/xmedia_channel/TEST_1?campaign_status[]=running&campaign_status[]=stopped&start_date=2016-10-01&end_date=2016-12-31"Retrieve data for a specific campaign starting on a certain date with cycle nesting
curl -H "Authorization: Bearer OAUTH_ACCESS_TOKEN" \ "https://api.localiqservices.com/client_reports/xmedia_channel/TEST_1?global_master_campaign_id[]=USA_14&start_date=2016-10-01&end_date=2016-12-31&include_cycles=true"Retrieve data for specific channels
curl -H "Authorization: Bearer OAUTH_ACCESS_TOKEN" \ "https://api.localiqservices.com/client_reports/xmedia_channel/TEST_1?global_master_campaign_id[]=USA_14&start_date=2016-10-01&end_date=2016-12-31&channels[]=display&channels[]=search"
| Field Name | Datatype | Description |
|---|---|---|
api_name |
String | Name of the API |
api_run_date |
String | Date report was run |
earliest_date_available |
String | Earliest Data is Available |
start_date |
String | Start date of report |
end_date |
String | End date of report |
time_zone |
String | Time Zone |
interval_size |
String | Interval Size ('none', 'day', 'calendar_week' or 'calendar_month') |
currency |
String | Currency Type of Monetary Values Returned in Report (Example: USD, AUD, CAD) |
global_master_advertiser_id |
String | Global Master Advertiser ID |
advertiser_name |
String | Name of the Advertiser |
report_data |
Object | Report details |
Report Data Object
| Field Name | Datatype | Description |
|---|---|---|
campaigns |
Object | Data for specified campaign.Campaigns. |
totals |
Object | Data for Overall Totals Totals Object. |
totals_per_interval |
Object | Overall Totals Broken Down by Interval Totals by Interval Object. |
totals_by_channel |
Object | Overall Totals Broken Down by Channel Totals Per Channel Object. |
totals_by_publisher |
Object | Overall Totals Broken Down by Publisher Totals Per Publisher Object. |
| Field Name | Datatype | Description |
|---|---|---|
| name | String | Campaign Name |
| global_master_campaign_id | String | Unique Identifier for Campaign |
| organization | String | Either reachlocal or gannett |
| start_date | String | Campaign Start Date |
| end_date | String | Campaign End Date |
| type | String | Type of Campaign |
| status | String | Status of Campaign |
| goals | Array | Array of Goals |
| cycles | Cycle[] | Array of Cycles |
| impressions | Int | Total Impressions for Campaign |
| clicks | Float | Total Clicks for Campaign |
| views | Float | Total Views for Campaign which is the Clicks if Publisher_ID is 65 |
| click_to_calls | Int | Total Click-to-Calls for Campaign. This is the count of clicks associated with a phone call. Calls to the same campaign from the same number are counted as one click_to_call. |
| calls | Int | Total Calls for Campaign |
| qualified_web_events | Int | Total Lead Generating CVT/Web Events for Campaign |
| non_qualified_web_events | Int | Total Non-Lead Generating CVT/Web Events for Campaign |
| emails | Int | Total Emails for Campaign |
| chats | Int | Total chat generated by paid traffic for Campaign |
| leads | Int | Total Leads for Campaign (calls + email + chat + qualified web events) |
| spend | Float | Total Spend for Campaign |
| ctr | Float | Click-through Rate for Campaign |
| cpc | Float | Cost Per Click for Campaign |
| cpl | Float | Cost Per Lead for Campaign |
Cycles Array
| Field Name | Datatype | Description |
|---|---|---|
| campaign_cycle | String | Unique Identifier for Cycle |
| start_date | String | Cycle Start Date |
| end_date | String | Cycle End Date |
| impressions | Int | Total Impressions for Cycle |
| clicks | Float | Total Clicks for Cycle |
| click_to_calls | Int | Total Click-to-Calls for Cycle. This is the count of clicks associated with a phone call. Calls to the same campaign from the same number are counted as one click_to_call. |
| calls | Int | Total Calls for Cycle |
| qualified_web_events | Int | Total Lead Generating CVT/Web Events for Cycle |
| non_qualified_web_events | Int | Total Non-Lead Generating CVT/Web Events for Cycle |
| emails | Int | Total Emails for Cycle |
| chats | Int | Total chat generated by paid traffic for Cycle |
| leads | Int | Total Leads for Cycle (calls + email + chat + qualified web events) |
| spend | Float | Total Spend for Cycle |
| ctr | Float | Click-through Rate for Cycle |
| cpc | Float | Cost Per Click for Cycle |
| wpcs | WPC[] | Array of WPCs |
| cpl | Float | Cost Per Lead for Cycle |
WPC Object
| Field Name | Datatype | Description |
|---|---|---|
| id | String | Unique Identifier for WPC |
| name | String | Name of WPC |
| channel | String | Channel for WPC |
| geo_type | String | GeoType for WPC |
| start_date | String | WPC Start Date |
| end_date | String | WPC End Date |
| tactic | String | Tactic for WPC (Offer Name) |
| external_account_id | String | External Account ID for WPC |
| external_account_name | String | External Account Name for WPC |
| impressions | Int | Total Impressions for WPC |
| clicks | Float | Total Clicks for WPC |
| views | Float | Total Views for WPC |
| click_to_calls | Int | Total Click-to-Calls for WPC. This is the count of clicks associated with a phone call. Calls to the same campaign from the same number are counted as one click_to_call. |
| calls | Int | Total Calls for WPC |
| qualified_web_events | Int | Total Lead Generating CVT/Web Events for WPC |
| non_qualified_web_events | Int | Total Non-Lead Generating CVT/Web Events for WPC |
| emails | Int | Total Emails for WPC |
| chats | Int | Total chat generated by paid traffic for WPC |
| leads | Int | Total Leads for WPC (calls + email + chat + qualified web events) |
| spend | Float | Total Spend for WPC |
| ctr | Float | Click-through Rate for WPC |
| cpc | Float | Cost Per Click for WPC |
| cpl | Float | Cost Per Lead for WPC |
| intervals | Interval[] | Array of Intervals |
| Field Name | Datatype | Description |
|---|---|---|
| start_date | String | Start Date for Interval |
| impressions | Int | Total Impressions for Interval |
| clicks | Float | Total Clicks for Interval |
| views | Float | Total Views for Interval |
| click_to_calls | Int | Total Click-to-Calls for Interval. This is the count of clicks associated with a phone call. Calls to the same campaign from the same number are counted as one click_to_call. |
| calls | Int | Total Calls for Interval |
| qualified_web_events | Int | Total Lead Generating CVT/Web Events for Interval |
| non_qualified_web_events | Int | Total Non-Lead Generating CVT/Web Events for Interval |
| emails | Int | Total Emails for Interval |
| chats | Int | Total chat generated by paid traffic for Interval |
| leads | Int | Total Leads for Interval (calls + email + chat + qualified web events) |
| spend | Float | Total Spend for Interval |
| ctr | Float | Click-through Rate for Interval |
| cpc | Float | Cost Per Click for Interval |
| cpl | Float | Cost Per Lead for Interval |
| Field Name | Datatype | Description |
|---|---|---|
| impressions | Int | Total Impressions |
| clicks | Float | Total Clicks |
| views | Float | Total Views |
| click_to_calls | Int | Total Click-to-Calls. This is the count of clicks associated with a phone call. Calls to the same campaign from the same number are counted as one click_to_call. |
| calls | Int | Total Calls |
| qualified_web_events | Int | Total Lead Generating CVT/Web Events |
| non_qualified_web_events | Int | Total Non-Lead Generating CVT/Web Events Web Events |
| emails | Float | Total Emails |
| chats | Float | Total chat generated by paid traffic |
| leads | Float | Total Leads (calls + email + chat + qualified web events) |
| spend | Float | Total Spend |
| ctr | Float | Overall Click-through Rate |
| cpc | Float | Overall Cost Per Click |
| cpl | Float | Overall Cost Per Lead |
| Field Name | Datatype | Description |
|---|---|---|
| start_date | String | Campaign Start Date |
| impressions | Int | Total Impressions for Interval |
| clicks | Float | Total Clicks for Interval |
| views | Float | Total Views for Interval |
| click_to_calls | Int | Total Click-to-Calls for Interval. This is the count of clicks associated with a phone call. Calls to the same campaign from the same number are counted as one click_to_call. |
| calls | Int | Total Calls for Interval |
| qualified_web_events | Int | Total Lead Generating CVT/Web Events for Interval |
| non_qualified_web_events | Int | Total Non-Lead Generating CVT/Web Events for Interval |
| emails | Int | Total Emails for Interval |
| chats | Int | Total chat generated by paid traffic for Interval |
| leads | Int | Total Leads for Interval (calls + email + chat + qualified web events) |
| spend | Float | Total Spend for Interval |
| ctr | Float | Click-through Rate for Interval |
| cpc | Float | Cost Per Click for Interval |
| cpl | Float | Cost Per Lead for Interval |
| Field Name | Datatype | Description |
|---|---|---|
| channel | String | Channel Name |
| impressions | Int | Total Impressions for Channel |
| clicks | Float | Total Clicks for Channel |
| views | Float | Total Views for Channel |
| click_to_calls | Int | Total Click-to-Calls for Channel. This is the count of clicks associated with a phone call. Calls to the same campaign from the same number are counted as one click_to_call. |
| calls | Int | Total Calls for Channel |
| qualified_web_events | Int | Total Lead Generating CVT/Web Events for Channel |
| non_qualified_web_events | Int | Total Non-Lead Generating CVT/Web Events for Channel |
| emails | Int | Total Emails for Channel |
| chats | Int | Total chat generated by paid traffic for Channel |
| leads | Int | Total Leads for Channel (calls + email + chat + qualified web events) |
| spend | Float | Total Spend for Channel |
| ctr | Float | Click-through Rate for Channel |
| cpc | Float | Cost Per Click for Channel |
| cpl | Float | Cost Per Lead for Channel |
| Field Name | Datatype | Description |
|---|---|---|
| publisher | String | Publisher Name |
| impressions | Int | Total Impressions for Publisher |
| clicks | Float | Total Clicks for Publisher |
| views | Float | Total Views for Publisher |
| click_to_calls | Int | Total Click-to-Calls for Publisher. This is the count of clicks associated with a phone call. Calls to the same campaign from the same number are counted as one click_to_call. |
| calls | Int | Total Calls for Publisher |
| qualified_web_events | Int | Total Lead Generating CVT/Web Events for Publisher |
| non_qualified_web_events | Int | Total Non-Lead Generating CVT/Web Events for Publisher |
| emails | Int | Total Emails for Publisher |
| chats | Int | Total chat generated by paid traffic for Publisher |
| leads | Int | Total Leads for Publisher |
| spend | Float | Total Spend for Publisher |
| ctr | Float | Click-through Rate for Publisher |
| cpc | Float | Cost Per Click for Publisher |
| cpl | Float | Cost Per Lead for Publisher |
Example Response with include_cycles=true
{
"api_name": "xmedia_channel",
"api_run_date": "2020-09-24",
"earliest_date_available": "2020-09-10",
"start_date": "2020-09-15",
"end_date": "2020-09-15",
"time_zone": "America/Los_Angeles",
"interval_size": "day",
"currency": "USD",
"global_master_advertiser_id": "TEST_1",
"advertiser_name": "Advertiser (Demo)",
"report_data": {
"campaigns": [
{
"name": "Xmedia Campaign (Demo)",
"global_master_campaign_id": "TEST_24638",
"organization": "reachlocal",
"start_date": "2020-09-10",
"end_date": null,
"type": "xmedia",
"status": "running",
"goals": [
{
"goal_type": "CPL"
},
{
"goal_type": "Contacts (Dynamic Ads - Automotive)"
}
],
"impressions": 1069,
"clicks": 17,
"views": 8,
"click_to_calls": 10,
"calls": 10,
"qualified_web_events": 2,
"non_qualified_web_events": 2,
"emails": 8,
"chats": 8,
"leads": 28,
"spend": 25.0,
"ctr": 1.59,
"cpc": 1.47,
"cpl": 0.89,
"cycles": [
{
"campaign_cycle": "TEST_24639",
"start_date": "2020-09-10",
"end_date": null,
"impressions": 1069,
"clicks": 17,
"views": 8,
"click_to_calls": 10,
"calls": 10,
"qualified_web_events": 2,
"non_qualified_web_events": 2,
"emails": 8,
"chats": 8,
"leads": 28,
"spend": 25.0,
"ctr": 1.59,
"cpc": 1.47,
"cpl": 0.89,
"wpcs": [
{
"id": 24640,
"name": "Search National",
"channel": "search",
"geo_type": "National",
"start_date": "2020-09-10",
"end_date": null,
"tactic": "Omnichannel - Smart",
"external_account_id": "12345",
"external_account_name": "test",
"impressions": 213,
"clicks": 3,
"views": 3,
"click_to_calls": 2,
"calls": 2,
"qualified_web_events": 0,
"non_qualified_web_events": 0,
"emails": 1,
"chats": 1,
"leads": 4,
"spend": 5.0,
"ctr": 1.41,
"cpc": 1.67,
"cpl": 1.25,
"intervals": [
{
"start_date": "2020-09-15",
"impressions": 213,
"clicks": 3,
"views": 3,
"click_to_calls": 2,
"calls": 2,
"qualified_web_events": 0,
"non_qualified_web_events": 0,
"emails": 1,
"chats": 1,
"leads": 4,
"spend": 5.0,
"ctr": 1.41,
"cpc": 1.67,
"cpl": 1.25
}
]
},
{
"id": 24641,
"name": "Display National",
"channel": "display",
"geo_type": "National",
"start_date": "2020-09-10",
"end_date": null,
"tactic": "Omnichannel - Smart",
"external_account_id": "12345",
"external_account_name": "test",
"impressions": 213,
"clicks": 3,
"views": 3,
"click_to_calls": 2,
"calls": 2,
"qualified_web_events": 0,
"non_qualified_web_events": 0,
"emails": 1,
"chats": 1,
"leads": 4,
"spend": 5.0,
"ctr": 1.41,
"cpc": 1.67,
"cpl": 1.25,
"intervals": [
{
"start_date": "2020-09-15",
"impressions": 213,
"clicks": 3,
"views": 3,
"click_to_calls": 2,
"calls": 2,
"qualified_web_events": 0,
"non_qualified_web_events": 0,
"emails": 1,
"chats": 1,
"leads": 4,
"spend": 5.0,
"ctr": 1.41,
"cpc": 1.67,
"cpl": 1.25
}
]
},
{
"id": 24643,
"name": "YouTube National",
"channel": "other",
"geo_type": "National",
"start_date": "2020-09-10",
"end_date": null,
"tactic": "Omnichannel - Smart",
"external_account_id": "12345",
"external_account_name": "test",
"impressions": 213,
"clicks": 3,
"views": 3,
"click_to_calls": 2,
"calls": 2,
"qualified_web_events": 0,
"non_qualified_web_events": 0,
"emails": 1,
"chats": 1,
"leads": 4,
"spend": 5.0,
"ctr": 1.41,
"cpc": 1.67,
"cpl": 1.25,
"intervals": [
{
"start_date": "2020-09-15",
"impressions": 213,
"clicks": 3,
"views": 3,
"click_to_calls": 2,
"calls": 2,
"qualified_web_events": 0,
"non_qualified_web_events": 0,
"emails": 1,
"chats": 1,
"leads": 4,
"spend": 5.0,
"ctr": 1.41,
"cpc": 1.67,
"cpl": 1.25
}
]
},
{
"id": 24644,
"name": "Social National",
"channel": "social",
"geo_type": "National",
"start_date": "2020-09-10",
"end_date": null,
"tactic": "Omnichannel - Smart",
"external_account_id": "12345",
"external_account_name": "test",
"impressions": 213,
"clicks": 3,
"views": 3,
"click_to_calls": 2,
"calls": 2,
"qualified_web_events": 0,
"non_qualified_web_events": 0,
"emails": 1,
"chats": 1,
"leads": 4,
"spend": 5.0,
"ctr": 1.41,
"cpc": 1.67,
"cpl": 1.25,
"intervals": [
{
"start_date": "2020-09-15",
"impressions": 213,
"clicks": 3,
"views": 3,
"click_to_calls": 2,
"calls": 2,
"qualified_web_events": 0,
"non_qualified_web_events": 0,
"emails": 1,
"chats": 1,
"leads": 4,
"spend": 5.0,
"ctr": 1.41,
"cpc": 1.67,
"cpl": 1.25
}
]
},
{
"id": 24645,
"name": "Chat National",
"channel": "chat",
"geo_type": "National",
"start_date": "2020-09-10",
"end_date": null,
"tactic": "Omnichannel - Smart",
"external_account_id": "12345",
"external_account_name": "test",
"impressions": 217,
"clicks": 5,
"views": 3,
"click_to_calls": 2,
"calls": 2,
"qualified_web_events": 2,
"non_qualified_web_events": 2,
"emails": 4,
"chats": 4,
"leads": 12,
"spend": 5.0,
"ctr": 2.3,
"cpc": 1.0,
"cpl": 0.42,
"intervals": [
{
"start_date": "2020-09-15",
"impressions": 217,
"clicks": 5,
"views": 3,
"click_to_calls": 2,
"calls": 2,
"qualified_web_events": 2,
"non_qualified_web_events": 2,
"emails": 4,
"chats": 4,
"leads": 12,
"spend": 5.0,
"ctr": 2.3,
"cpc": 1.0,
"cpl": 0.42
}
]
}
]
}
]
}
],
"totals": {
"impressions": 1069,
"clicks": 17,
"views": 8,
"click_to_calls": 10,
"calls": 10,
"qualified_web_events": 2,
"non_qualified_web_events": 2,
"emails": 8,
"chats": 8,
"leads": 28,
"spend": 25.0,
"ctr": 1.59,
"cpc": 1.47,
"cpl": 0.89
},
"totals_per_interval": [
{
"start_date": "2020-09-15",
"impressions": 1069,
"clicks": 17,
"views": 8,
"click_to_calls": 10,
"calls": 10,
"qualified_web_events": 2,
"non_qualified_web_events": 2,
"emails": 8,
"chats": 8,
"leads": 28,
"spend": 25.0,
"ctr": 1.59,
"cpc": 1.47,
"cpl": 0.89
}
],
"totals_by_channel": [
{
"channel": "search",
"impressions": 213,
"clicks": 3,
"views": 3,
"click_to_calls": 2,
"calls": 2,
"qualified_web_events": 0,
"non_qualified_web_events": 0,
"emails": 1,
"chats": 1,
"leads": 4,
"spend": 5.0,
"ctr": 1.41,
"cpc": 1.67,
"cpl": 1.25
},
{
"channel": "display",
"impressions": 213,
"clicks": 3,
"views": 3,
"click_to_calls": 2,
"calls": 2,
"qualified_web_events": 0,
"non_qualified_web_events": 0,
"emails": 1,
"chats": 1,
"leads": 4,
"spend": 5.0,
"ctr": 1.41,
"cpc": 1.67,
"cpl": 1.25
},
{
"channel": "other",
"impressions": 213,
"clicks": 3,
"views": 3,
"click_to_calls": 2,
"calls": 2,
"qualified_web_events": 0,
"non_qualified_web_events": 0,
"emails": 1,
"chats": 1,
"leads": 4,
"spend": 5.0,
"ctr": 1.41,
"cpc": 1.67,
"cpl": 1.25
},
{
"channel": "social",
"impressions": 213,
"clicks": 3,
"views": 3,
"click_to_calls": 2,
"calls": 2,
"qualified_web_events": 0,
"non_qualified_web_events": 0,
"emails": 1,
"chats": 1,
"leads": 4,
"spend": 5.0,
"ctr": 1.41,
"cpc": 1.67,
"cpl": 1.25
},
{
"channel": "lsa",
"impressions": 2917,
"clicks": 31,
"views": 3,
"click_to_calls": 32,
"calls": 32,
"qualified_web_events": 0,
"non_qualified_web_events": 0,
"emails": 13,
"chats": 13,
"leads": 58,
"spend": 58.38,
"ctr": 1.06,
"cpc": 1.88,
"cpl": 1.01
},
{
"channel": "chat",
"impressions": 217,
"clicks": 5,
"views": 5,
"click_to_calls": 2,
"calls": 2,
"qualified_web_events": 2,
"non_qualified_web_events": 2,
"emails": 4,
"chats": 4,
"leads": 12,
"spend": 5.0,
"ctr": 2.3,
"cpc": 1.0,
"cpl": 0.42
},
"channel": "video",
"impressions": 580,
"clicks": 6,
"views": 6,
"click_to_calls": 6,
"calls": 6,
"qualified_web_events": 0,
"non_qualified_web_events": 0,
"emails": 3,
"chats": 3,
"leads": 12,
"spend": 12.51,
"ctr": 1.03,
"cpc": 2.09,
"cpl": 1.04
},
],
"totals_by_publisher": [
{
"publisher": "Google",
"publisher_id": 1,
"impressions": 213,
"clicks": 3,
"views": 3,
"click_to_calls": 2,
"calls": 2,
"qualified_web_events": 0,
"non_qualified_web_events": 0,
"emails": 1,
"chats": 1,
"leads": 4,
"spend": 5.0,
"ctr": 1.41,
"cpc": 1.67,
"cpl": 1.25
},
{
"publisher": "Simpli.fi API",
"publisher_id": 49,
"impressions": 213,
"clicks": 3,
"views": 3,
"click_to_calls": 2,
"calls": 2,
"qualified_web_events": 0,
"non_qualified_web_events": 0,
"emails": 1,
"chats": 1,
"leads": 4,
"spend": 5.0,
"ctr": 1.41,
"cpc": 1.67,
"cpl": 1.25
},
{
"publisher": "Youtube - Google",
"publisher_id": 65,
"impressions": 213,
"clicks": 3,
"views": 3,
"click_to_calls": 2,
"calls": 2,
"qualified_web_events": 0,
"non_qualified_web_events": 0,
"emails": 1,
"chats": 1,
"leads": 4,
"spend": 5.0,
"ctr": 1.41,
"cpc": 1.67,
"cpl": 1.25
},
{
"publisher": "Facebook",
"publisher_id": 38,
"impressions": 213,
"clicks": 3,
"views": 3,
"click_to_calls": 2,
"calls": 2,
"qualified_web_events": 0,
"non_qualified_web_events": 0,
"emails": 1,
"chats": 1,
"leads": 4,
"spend": 5.0,
"ctr": 1.41,
"cpc": 1.67,
"cpl": 1.25
},
{
"publisher": "Apex Chat - VendoMax Inc.",
"publisher_id": 1400,
"impressions": 217,
"clicks": 5,
"views": 5,
"click_to_calls": 2,
"calls": 2,
"qualified_web_events": 2,
"non_qualified_web_events": 2,
"emails": 4,
"chats": 4,
"leads": 12,
"spend": 5.0,
"ctr": 2.3,
"cpc": 1.0,
"cpl": 0.42
}
]
}
}
Lead Info APIs/Webhooks
We have HIPAA Compliant APIs, Webhooks and apps on the Zapier marketplace to support CRM integrations.
API (Interface to the data)
- Contacts
- Contact Interactions
Webhook (Event driven automated interface to the data)
- Contacts
- Contact Interactions
Apps on Zapier Marketplace
- Contacts
- Contact Interactions
Contacts/Lead APIs
Contacts
Summary: This HIPAA Compliant endpoint supports integration with CRM products. It returns all contacts (first name, last name, email and/or phone number) generated by a campaign for an advertiser. The response is organized by campaigns with the contacts nested within. Please note that the response also includes the associated contact and its meta data.
Parameters: It requires the following parameters for a successful response: GMAID (advertiser ID), created_before date and created_after_date.
Recommended usage pattern: A one-time call to the API to fetch all past interactions recorded by the LocaliQ platform, followed by daily recurrent calls for a 2 -3-day period to fetch new interactions. The results are paginated. If there is no data for a particular attribute, it will not be present in the results.
Please note that the contact information in this endpoint is for linking the interactions/leads with the contact. Importing them as contacts into your CRM from this endpoint will cause duplicates.
Resource Overview
| Method | URI Format |
|---|---|
| GET | /crm/contacts?[params] |
Parameters
| Parameter | Required | Description |
|---|---|---|
| global_master_advertiser_id | yes | The global master advertiser id (for example, TEST_1). |
| created_after_date | yes | Specifies the lower bound for the earliest date and time when searching for contacts. All contacts returned in the response will have been created on or after this date. The format expected is YYYY-MM-DD. |
| created_before_date | yes | Specifies the upper bound for the latest date and time when searching for contacts. All contacts returned in the response will have been created before this date. The format expected is YYYY-MM-DD. |
| page | no | The page number of the paginated result set to return. This parameter is optional, but if the page requested doesn’t exist in the result set defined by the other parameters an empty JSON array is returned Default value: 1. |
Response Data Details
require 'uri'
require 'net/http'
url = URI("https://api.localiqservices.com/crm/contacts?global_master_advertiser_id=TEST_1&created_after_date=2019-01-01&created_before_date=2019-01-10")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'OAUTH_ACCESS_TOKEN'
response = http.request(request)
puts response.read_body
OkHttpClient client = new OkHttpClient();
Request request = new Request.Builder()
.url("https://api.localiqservices.com/crm/contacts?global_master_advertiser_id=TEST_1&created_after_date=2019-01-01&created_before_date=2019-01-10")
.get()
.addHeader("Authorization", "OAUTH_ACCESS_TOKEN")
.build();
Response response = client.newCall(request).execute();
curl --request GET \
--url 'https://api.localiqservices.com/crm/contacts?global_master_advertiser_id=TEST_1&created_after_date=2019-01-01&created_before_date=2019-01-10' \
--header 'Authorization: OAUTH_ACCESS_TOKEN'
Example Response
{
"global_master_advertiser_id": "TEST_1",
"page": 1,
"total_pages": 2,
"next_page_location": "https://api.localiqservices.com/crm/contacts?created_after_date=2019-01-01&created_before_date=2019-01-10&global_master_advertiser_id=TEST_1&page=2",
"contacts": [
{
"status": "pending_contact",
"id": 862741,
"created_at": "2019-01-04T15:24:31Z",
"tags": [],
"first_name": "Charlie",
"last_name": "Bucket",
"email": "charlie.bucket@google.com",
"phone_work": "2188675309",
"address1": "21700 Oxnard st",
"address2": "suite 1600",
"city": "Woodland hills",
"state": "California",
"postal": "91367",
"country": "United States of America"
},
{
"status": "pending_contact",
"id": 864211,
"created_at": "2019-01-04T18:21:53Z",
"tags": [],
"first_name": "Augustus",
"email": "augustus.gloop@gmail.com"
},
{
"status": "pending_contact",
"id": 868881,
"created_at": "2019-01-08T18:42:53Z",
"tags": [
"TRACY WONG'S FERRARI DEALERSHIP"
],
"first_name": "Mike",
"last_name": "Teavee",
"email": "mike.reavee@gmail.com",
"phone_work": ""
},
{
"status": "pending_contact",
"id": 869231,
"created_at": "2019-01-08T20:51:03Z",
"tags": [],
"first_name": "Violet",
"last_name": "Beauregarde",
"email": "violet.beauregarde@gmail.com",
"phone_work": "6128675309",
"address1": "1234 Oak St",
"city": "Springfield",
"state": "CA",
"postal": "90210",
"country": "United States Minor Outlying Islands"
},
{
"status": "pending_contact",
"id": 869271,
"created_at": "2019-01-08T21:43:31Z",
"tags": [
"Direct Site Traffic"
],
"first_name": "Veruca",
"last_name": "Salt",
"email": "veruca.salt@gmail.com",
"phone_work": "9525551212"
}
...
]
}
The body of the API response will contain metadata and a JSON array of contact objects.
MetaData
| Field Name | Description |
|---|---|
| global_master_advertiser_id | Global Master Advertiser ID of the contacts requested |
| page | Current page number being displayed |
| total_pages | Total number of pages of results |
| next_page_location | Complete URL that can be used to retrieve the next page of results. Will be null if there are no more pages. |
Contact
| Field | Type | Description |
|---|---|---|
| id | Integer | An integer uniquely identifying this contact. |
| first_name | String | The first name of the contact. The field is nullable |
| last_name | String | The last name of the contact. The field is nullable |
| String | The email address of the contact. The field is nullable |
|
| company | String | The company name for this contact. The field is nullable |
| title | String | The title for this contact. The field is nullable |
| phone_home | String | The home phone number for this contact. The field is nullable |
| phone_work | String | The work phone number for this contact. The field is nullable |
| phone_mobile | String | The mobile phone number for this contact. The field is nullable |
| phone_fax | String | The fax phone number for this contact. The field is nullable |
| address1 | String | The first address line for this contact. The field is nullable |
| address2 | String | The second address line for this contact. The field is nullable |
| city | String | The city for this contact. The field is nullable |
| state | String | The state for this contact. The field is nullable |
| postal | String | The postal code for this contact. The field is nullable |
| country | String | The country for this contact. The field is nullable |
| notes | String | Free form text notes entered by end users for the contact. The field is nullable |
| tags | Array of String | When present represents a collection of tags use for applying ad-hoc categorization and collation of contacts. The field is nullable |
| status | String | The status of the contact. Valid values are pending_contact, active_lead, client and none. |
| created_at | Datetime | The date and time which this contact was created. The field is nullable |
| archived_at | Datetime | The date and time which this contact was archived. The field is nullable |
Contact Interactions/Leads
Summary: This HIPAA Compliant endpoint supports integration with CRM products. It returns all interactions (or leads) generated by a campaign for an advertiser. The response is organized by campaigns with the interactions nested within. Please note that the response also includes the associated contact and its meta data.
Parameters: It requires the following parameters for a successful response: GMAID (advertiser ID), created_before date and created_after_date. An optional event_type parameter can be specified, to limit results to one of chat, call, or form.
Recommended usage pattern: A one-time call to the API to fetch all past interactions recorded by the LocaliQ platform, followed by daily recurrent calls for a 2 -3-day period to fetch new interactions. The results are paginated. If there is no data for a particular attribute, it will not be present in the results.
Please note that the contact information in this endpoint is for linking the interactions/leads with the contact. Importing them as contacts into your CRM from this endpoint will cause duplicates.
Please note: If you have the Live Chat Platinum product, the API response can contain non-lead chat information. A non-lead chat is in which the visitor does not provide their contact details (i.e. their name + email or phone). The contact information in the response is mock data. If you would like to remove non-lead chats from your integration, please filter out interactions containing the email "nonleadchat@reachlocal.com".
Resource Overview
| Method | URI Format |
|---|---|
| GET | /crm/contact_interactions?[params] |
| GET | /crm/contact_interactions/:id |
Parameters
| Parameter | Required | Description |
|---|---|---|
| global_master_advertiser_id | yes | The global master advertiser id (for example, TEST_1). |
| created_after_date | yes | Specifies the lower bound for the earliest date and time when searching for contact interactions. All records returned in the response will have been created on or after this date. The format expected is YYYY-MM-DD. |
| created_before_date | yes | Specifies the upper bound for the latest date and time when searching for contact interactions. All records returned in the response will have been created before this date. The format expected is YYYY-MM-DD. |
| page | no | The page number of the paginated result set to return. This parameter is optional, but if the page requested doesn’t exist in the result set defined by the other parameters an empty JSON array is returned. Default value: 1 |
| event_type | no | Must be one of chat, call, or form. Limits results to records of that type. |
Response Data Details
require 'uri'
require 'net/http'
url = URI("https://api.localiqservices.com/crm/contact_interactions?global_master_advertiser_id=TEST_1&created_after_date=2019-01-01&created_before_date=2019-01-10")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'OAUTH_ACCESS_TOKEN'
response = http.request(request)
puts response.read_body
OkHttpClient client = new OkHttpClient();
Request request = new Request.Builder()
.url("https://api.localiqservices.com/crm/contact_interactions?global_master_advertiser_id=TEST_1&created_after_date=2019-01-01&created_before_date=2019-01-10")
.get()
.addHeader("Authorization", "OAUTH_ACCESS_TOKEN")
.build();
Response response = client.newCall(request).execute();
curl --request GET \
--url 'https://api.localiqservices.com/crm/contact_interactions?global_master_advertiser_id=TEST_1&created_after_date=2019-01-01&created_before_date=2019-01-10' \
--header 'Authorization: OAUTH_ACCESS_TOKEN'
Example Response
{
"global_master_advertiser_id": "TEST_1",
"page": 1,
"total_pages": 5,
"next_page_location": "https://api.localiqservices.com/crm/contact_interactions?created_after_date=2019-01-01&created_before_date=2023-02-10&global_master_advertiser_id=TEST_1&page=2",
"contact_interactions": [
{
"campaign_id": 400904,
"campaign_name": "Organic Search",
"id": 755428239,
"created_at": "2023-01-04T15:31:11-08:00",
"occured_at": "2023-01-04T15:28:46-08:00",
"read_at": "2023-01-05T10:59:42-08:00",
"tags": [
"Call Lead",
"Organic Search"
],
"event_type": "call",
"contact_id": 432323455,
"status": "pending_contact",
"display_name": "Flintstone, Fred",
"contact": {
"status": "pending_contact",
"id": 432323455,
"created_at": "2023-01-04T15:31:11-08:00",
"tags": [
"Organic Search"
],
"first_name": "Fred",
"last_name": "Flintstone",
"company": "",
"phone_work": "+12627071229",
"address1": "1234 Elm Street",
"city": "Peoria",
"state": "IL",
"postal": "53095"
},
"call": {
"occured_at": "2023-01-04T15:28:46-08:00",
"target_number": "1231231234",
"recording_url": "https://webservice.telmetrics.com/filedownload.ashx/bb01bae3-f6d4-4e1b-b295-481e92a7dd5e/2697305168.mp3",
"duration": "00:55"
}
},
{
"campaign_id": 26330,
"campaign_name": "Direct Site Traffic",
"id": 1013951,
"created_at": "2019-01-07T13:26:09-08:00",
"occured_at": "2019-01-07T13:26:05-08:00",
"tags": [
"Direct Site Traffic",
"Facebook"
],
"event_type": "form",
"contact_id": 9941,
"status": "pending_contact",
"display_name": "asdf",
"contact": {
"status": "pending_contact",
"id": 9941,
"created_at": "2017-11-16T11:11:04-08:00",
"tags": [
"Direct Site Traffic"
],
"first_name": "asdf",
"last_name": "",
"email": "asdf@asdf.com",
"phone_work": "asdf",
"company": "Slate Quarry",
"address1": "123 Rubble Street",
"address2": "Suite 1",
"city": "Bedrock",
"state": "AZ",
"postal": "86046",
"country": "USA"
},
"form": {
"sub_type": "FormEmail",
"subject": "Hi",
"full_message": "Message:\nasdf",
"message": "asdf",
"extra_fields": {}
},
"archived_at": "2019-01-08T13:26:05-08:00"
},
{
"campaign_id": 48127271,
"master_campaign_id": "390971619",
"campaign_name": "GCI | SA Smart | Squirrel Feed",
"id": 185074076,
"created_at": "2022-12-25T12:37:57-05:00",
"occured_at": "2022-12-25T12:37:55-05:00",
"tags": [
"Facebook Lead",
"Form Lead",
"GCI | SA Smart | Squirrel Feed"
],
"event_type": "form",
"contact_id": 91774815,
"status": "pending_contact",
"display_name": "Pez, Dispenser",
"contact": {
"status": "pending_contact",
"id": 91774815,
"created_at": "2022-12-25T12:37:57-05:00",
"tags": [
"GCI | SA Smart | Squirrel Feed"
],
"first_name": "Dispenser",
"last_name": "Pez",
"phone_work": "5555555095",
"postal": "90732",
"email": "pez@gmail.com"
},
"form": {
"sub_type": "FormPost",
"full_message": "",
"extra_fields": {
"fullName": "Dispenser Pez",
"zip_code": "90732",
"full_name": "Dispenser Pez",
"phone_number": "5555555095",
"are_you_the_homeowner?": "Yes",
"email": "pez@gmail.com"
}
}
},
{
"campaign_id": 28002633,
"campaign_name": "Organic Search",
"id": 1876526262,
"created_at": "2023-01-30T07:51:07-08:00",
"occured_at": "2023-01-30T07:51:05-08:00",
"tags": [
"Chat Lead",
"Organic Search",
"Sales Chat"
],
"event_type": "chat",
"contact_id": 9293472379,
"status": "pending_contact",
"display_name": "Geddy Lee",
"contact": {
"status": "pending_contact",
"id": 9293472379,
"created_at": "2023-01-30T07:51:07-08:00",
"tags": [
"Organic Search"
],
"first_name": "Geddy",
"last_name": "Lee",
"email": "bass_player@yahoo.com",
"phone_work": "262-555-0147",
"company": "Border Foods"
},
"chat": {
"summary": "Hello, I’m a Virtual Assistant ready to help. How can I help you?\r\nI need a ride to the gig.\r\nFor over 20 years, our commitment to customer service has made us the most professional transportation company on the North Shore of Boston. We have secured a reputation of outstanding dedication and service with our thousands of satisfied customers. Which of our services are you interested in?\r\nI need a ride to the gig.\r\nWe would be happy to help you. What is the date of your event?\r\nFebruary 10.2023\r\nThank you. May I have your name?\r\nGeddy\r\nThanks Geddy. How can we get in touch?\r\nEmail Me\r\nMay I have your email address?\r\n<a href='mailto:bass_player' target='blank'>bass_player@yahoo.com</a>\r\nMay we also have your phone number, to better follow up with you?\r\nSure\r\nPlease provide your phone number below.\r\n262-555-0147\r\nThank you. Is there anything else we should know?\r\nNo. Thank you \r\nThank you for contacting us. My staff will follow up with you.Have a great day!\r\n",
"transcript": [
{
"id": 1,
"timestamp": "1/30/2023 10:50:06 AM",
"from": "Virtual Assistant:",
"message": "Hello, I’m a Virtual Assistant ready to help. How can I help you?"
},
{
"id": 2,
"timestamp": "1/30/2023 10:50:09 AM",
"from": "Visitor:",
"message": "I need a ride to the gig."
},
{
"id": 3,
"timestamp": "1/30/2023 10:50:09 AM",
"from": "Virtual Assistant:",
"message": "For over 20 years, our commitment to customer service has made us the most professional transportation company on the North Shore of Lake Superior. We have secured a reputation of outstanding dedication and service with our hundreds of satisfied customers. Which of our services are you interested in?"
},
{
"id": 4,
"timestamp": "1/30/2023 10:50:31 AM",
"from": "Visitor:",
"message": "I need a ride to the gig."
},
{
"id": 5,
"timestamp": "1/30/2023 10:50:31 AM",
"from": "Virtual Assistant:",
"message": "We offer limousines, SUVs, and party buses that can fit up to 32 guests. We offer a wide variety of new vehicles that always leave our garage looking impeccable, as a luxury vehicle should. Our chauffeurs are always dressed appropriately, black suit and black tie or for formal events, a full tuxedo to add an air of distinction to your special occasion. Please tell me a bit about what you’re looking for."
},
{
"id": 6,
"timestamp": "1/30/2023 10:51:22 AM",
"from": "Visitor:",
"message": "I need a ride to the gig."
},
{
"id": 7,
"timestamp": "1/30/2023 10:51:22 AM",
"from": "Virtual Assistant:",
"message": "We would be happy to help you. What is the date of your event?"
},
{
"id": 8,
"timestamp": "1/30/2023 10:51:40 AM",
"from": "Visitor:",
"message": "February 10.2023"
},
{
"id": 9,
"timestamp": "1/30/2023 10:51:41 AM",
"from": "Virtual Assistant:",
"message": "Thank you. May I have your name?"
},
{
"id": 10,
"timestamp": "1/30/2023 10:51:50 AM",
"from": "Visitor:",
"message": "Geddy"
},
{
"id": 11,
"timestamp": "1/30/2023 10:51:50 AM",
"from": "Virtual Assistant:",
"message": "Thanks Geddy. How can we get in touch?"
},
{
"id": 12,
"timestamp": "1/30/2023 10:52:00 AM",
"from": "Visitor:",
"message": "Email Me"
},
{
"id": 13,
"timestamp": "1/30/2023 10:52:00 AM",
"from": "Virtual Assistant:",
"message": "May I have your email address?"
},
{
"id": 14,
"timestamp": "1/30/2023 10:52:12 AM",
"from": "Visitor:",
"message": "bass_player@yahoo.com"
},
{
"id": 15,
"timestamp": "1/30/2023 10:52:13 AM",
"from": "Virtual Assistant:",
"message": "May we also have your phone number, to better follow up with you?"
},
{
"id": 16,
"timestamp": "1/30/2023 10:52:22 AM",
"from": "Visitor:",
"message": "Sure"
},
{
"id": 17,
"timestamp": "1/30/2023 10:52:22 AM",
"from": "Virtual Assistant:",
"message": "Please provide your phone number below."
},
{
"id": 18,
"timestamp": "1/30/2023 10:52:35 AM",
"from": "Visitor:",
"message": "262-555-0147"
},
{
"id": 19,
"timestamp": "1/30/2023 10:52:36 AM",
"from": "Virtual Assistant:",
"message": "Thank you. Is there anything else we should know?"
},
{
"id": 20,
"timestamp": "1/30/2023 10:53:01 AM",
"from": "Visitor:",
"message": "No. Thank you"
},
{
"id": 21,
"timestamp": "1/30/2023 10:53:01 AM",
"from": "Virtual Assistant:",
"message": "Thank you for contacting us. My staff will follow up with you.Have a great day!"
},
{
"id": 22,
"timestamp": "1/30/2023 10:53:04 AM",
"from": "System:",
"message": "The chat session has ended."
}
]
}
}
]
}
The body of the API response will contain metadata and a JSON array of contact interaction objects.
MetaData
| Field Name | Description |
|---|---|
| global_master_advertiser_id | Global Master Advertiser ID of the contact interactions requested |
| page | Current page number being displayed |
| total_pages | Total number of pages of results |
| next_page_location | Complete URL that can be used to retrieve the next page of results. Will be null if there are no more pages. |
Contact Interaction
| Field | Type | Description |
|---|---|---|
| id | Integer | An integer uniquely identifying this contact interaction. |
| contact_id | Integer | An integer uniquely identifying the contact to which this contact interaction belongs. |
| campaign_id | Integer | An integer uniquely identifying the campaign that this contact interaction is attributed to. |
| campaign_name | String | The name of the campaign that this contact interaction is attributed to. |
| archived_at | Datetime | The date and time which this contact interaction was archived. The field is nullable |
| created_at | Datetime | The date and time which this contact interaction was created. |
| important_at | Datetime | The date and time which this contact interaction was marked important. The field is nullable |
| occured_at | Datetime | The date and time which this contact interaction occurred. This will usually be different than the date that the contact interaction was created. |
| read_at | Datetime | The date and time which this contact interaction was marked read. The field is nullable |
| display_name | String | The display name of the contact interaction. |
| event_type | String | The type of the contact interaction . Valid values are chat, call and form. |
| status | String | The status of the associated contact. Valid values are pending_contact, active_contact interaction, client and none. |
| notes | String | Free form text notes entered by end users onto the contact interaction . The field is nullable |
| tags | Array of String | When present represents a collection of tags use for applying ad-hoc categorization and collation of contact interactions The field is nullable. |
| contact | Contact | The contact to which this contact interaction belongs. See the contacts page of this document for details |
Depending on the type of contact interaction (see the event_type attribute), the payload will also include one of the following:
Chat
| Field | Type | Description |
|---|---|---|
| summary | String | A freeform text description of the chat. The field is nullable |
| transcript | Array | An ordered array of Chat transcript objects. |
| Field | Type | Description |
|---|---|---|
| id | Integer | A sequential id of the line chat transcript. It uniquely identifies a line of the chat transcript within this contact interaction. |
| timestamp | String | The date and time that the external chat API registered for this line of the chat transcript. |
| from | String | The display name of the member of the chat who sent this message. |
| message | String | The message body of this line of the chat transcript. |
| Field | Type | Description |
|---|---|---|
| occured_at | Datetime | The date and time that the call occurred. |
| duration | Integer | The duration of the call in seconds. |
| recording_url | String | The URL address to an audio recording of the call. |
| target_number | String | the business's phone number that rang. |
| dialed_umber | String | the tracking number that was shown to the user |
| caller_number | String | the caller's phone number |
| Field | Type | Description |
|---|---|---|
| sub_type | String | The subtype of the form. Valid values are FormPost and FormEmail. |
| full_message | String | The full form message |
| subject | String | The field is nullable |
| extra_fields | JSON Object with custom attributes | The field is nullable |
CRM Webhooks
Client Center Webhook
Client Center has an automation feature that is capable of triggering on “New Lead for New Contact” and “New Lead for Existing Contact” events. When either of these events occur, this webhook integration will trigger and POST the Lead Event JSON Payload to a URL configured for the webhook. Create a webhook using the integrations account setting.
When creating a webhook integration in Client Center, the CRM provider should be asked for the Payload URL.
Webhook Components:
- Payload URL
- A Payload URL (also called an Endpoint URL, Postback URL, or HTTP POST URL) is a place in the CRM where our data can be sent.
- We will not be able to send the data without a Payload URL.
- Payload URL Examples
https://api.crmprovider.com/contacthttps://www.crmprovider.net/lead/genericlead.asmxhttps://devdashboard.crmprovider.com/post/
- Authentication Header
- This section is optional and will only be used if there is a token that needs to be included in the header of the API call. This would consist of identifiable information like an ID or a code provided by the CRM to ensure that whoever is trying to send the data is actually who they say they are.
- Which events should trigger a webhook?
- Leads can be sent for New Contacts and/or Existing Contacts. Two webhooks would need to be created if an advertiser wanted to send data for both new and existing contacts, but the same information (Payload URL, Authentication Header, etc.) can be used for each.
- Which lead types should trigger a webhook?
- Leads can be filtered to only send Calls, only Chats, only Forms & Emails, or any combination of these three options.
- Payload Format
- The structure of the data in the webhook is the same as that returned by the API. This can either be sent in JSON, which is the standard format, or in ADF/XML.
- The webhook can be set to Active by checking the box next to "Active". If left unchecked, the webhook will not send data. Webhooks that continually fail will be automatically set to "Inactive".
All leads for an advertiser will be sent through the webhook and cannot be filtered by a specific campaign.
Custom Webhook
Register via API
Webhook option: We also have a Webhook to receive contacts in real time as they are recorded in the LocaliQ platform. Our endpoint enables registration for webhook callbacks when new contacts or contact interactions occur. It requires the following parameters for a successful response: GMAID (advertiser ID).
Zapier App: The contact webhook is available as an integration on the Zapier marketplace. https://zapier.com/apps/localiq/integrations
require 'uri'
require 'net/http'
url = URI("https://api.localiqservices.com/crm/webhooks?global_master_advertiser_id=TEST_1")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'OAUTH_ACCESS_TOKEN'
request["Content-Type"] = 'application/json'
request.body = "{ \"event_type\": \"new_contact\", \"url\": \"https://my.webhook.site/new_contact\", \"authorization\": \"token jokin\" }"
response = http.request(request)
puts response.read_body
OOkHttpClient client = new OkHttpClient();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{ \"event_type\": \"new_contact\", \"url\": \"https://my.webhook.site/new_contact\", \"authorization\": \"token jokin\" }");
Request request = new Request.Builder()
.url("https://api.localiqservices.com/crm/webhooks?global_master_advertiser_id=TEST_1")
.post(body)
.addHeader("Authorization", "OAUTH_ACCESS_TOKEN")
.addHeader("Content-Type", "application/json")
.build();
Response response = client.newCall(request).execute();
curl --request POST \
--url 'https://api.localiqservices.com/crm/webhooks?global_master_advertiser_id=TEST_1' \
--header 'Authorization: OAUTH_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '{ "event_type": "new_contact", "url": "https://my.webhook.site/9995ad74-3c32-4e6c-aa8f-25da0fd419d9/new_contact", "authorization": "token jokin" }'
The above command returns JSON structured like this:
{
"id": "84+TEST_1"
}
This ID will be needed in the event the user chooses to de-register the webhook.
Resource Overview
POST https://api.localiqservices.com/crm/webhooks
Parameters
| Parameter | Required | Description |
|---|---|---|
| global_master_advertiser_id | yes | The global master advertiser id (for example, TEST_1). |
Payload
| Key | Description |
|---|---|
| event_type | We support both new_contact and new_lead as event types. When event_type is new_contact, the registered webhook is created for new lead for a new contact. When the event_type is new_lead, the registered webhook is created for a new lead for an existing contact. |
| url | Endpoint Webhook should POST data to |
| authorization | Authorization for Endpoint Webhook POSTs data to |
Response Data Details The body of the API response will the id of the webhook.
MetaData
| Field Name | Description |
|---|---|
| id | identifier of the webhook registration. |
Deregister via API
This endpoint De-registers a webhook created using the above register webhook method. The ID returned by the register method is used to de-register the webhook.
require 'uri'
require 'net/http'
url = URI("https://api.localiqservices.com/crm/webhooks/84+TEST_1")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Delete.new(url)
request["Authorization"] = 'OAUTH_ACCESS_TOKEN'
request["Content-Type"] = 'application/json'
response = http.request(request)
puts response.read_body
OkHttpClient client = new OkHttpClient();
Request request = new Request.Builder()
.url("https://api.localiqservices.com/crm/webhooks/84+TEST_1")
.delete(null)
.addHeader("Authorization", "OAUTH_ACCESS_TOKEN")
.addHeader("Content-Type", "application/json")
.build();
Response response = client.newCall(request).execute();
curl --request DELETE \
--url 'https://api.localiqservices.com/crm/webhooks/84+TEST_1' \
--header 'Authorization: OAUTH_ACCESS_TOKEN' \
--header 'Content-Type: application/json'
The above command returns JSON structured like this:
{
"id": "84+TEST_1"
}
Resource Overview
DELETE https://api.localiqservices.com/crm/webhooks/[id]
Response Data Details
A response status code of 200 indicates that the webhook was successfully de-registered. A response status code of 404 indicates that the webhook ID was not found.
The body of the API response will be the id of the webhook that was deleted.
MetaData
| Field Name | Description |
|---|---|
| id | identifier of the webhook registration. |
Webhook Payload
The lead event that triggered the webhook will be sent to the specified payload URL as an HTTP POST with a content type of application/json.
Lead Object
| Field | Type | Description |
|---|---|---|
| id | Integer | An integer uniquely identifying this lead event. |
| contact_id | Integer | An integer uniquely identifying the contact to which this lead belongs. |
| campaign_id | Integer | An integer uniquely identifying the campaign that this lead is attributed to. |
| master_campaign_id | Integer | An integer uniquely identifying the campaign that this lead is attributed to. |
| campaign_name | String | The name of the campaign that this lead is attributed to. |
| archived_at | Datetime | The date and time which this lead event was archived. The field is nullable |
| created_at | Datetime | The date and time which this lead event was created. |
| important_at | Datetime | The date and time which this lead event was marked important. The field is nullable |
| occured_at | Datetime | The date and time which this lead event occurred. This will usually be different than the date that the lead event was created. |
| display_name | String | The display name of the lead event. |
| event_type | String | The type of the lead event. Valid values are chat, call and form. |
| status | String | The status of the associated contact. Valid values are pending_contact, active_lead, client and none. The field is nullable |
| notes | String | Free form text notes entered by end users onto the lead event. The field is nullable |
| tags | Array of String | When present represents a collection of tags use for applying ad-hoc categorization and collation of lead events. The field is nullable |
| contact | Contact | The contact to which this lead event belongs. |
| chat | Chat | The lead event payload will include a single chat, call or form object. The object type will match the event_type field. |
| call | Call | The lead event payload will include a single chat, call or form object. The object type will match the event_type field. |
| form | Form | The lead event payload will include a single chat, call or form object. The object type will match the event_type field. |
Contact Object
| Field | Type | Description |
|---|---|---|
| id | Integer | An integer uniquely identifying this contact. |
| first_name | String | The first name of the contact. The field is nullable |
| last_name | String | The last name of the contact. The field is nullable |
| String | The email address of the contact. The field is nullable |
|
| company | String | The company name for this contact. The field is nullable |
| title | String | The title for this contact. The field is nullable |
| phone_home | String | The home phone number for this contact. The field is nullable |
| phone_work | String | The work phone number for this contact. The field is nullable |
| phone_mobile | String | The mobile phone number for this contact. The field is nullable |
| phone_fax | String | The fax phone number for this contact. The field is nullable |
| address1 | String | The first address line for this contact. The field is nullable |
| address2 | String | The second address line for this contact. The field is nullable |
| city | String | The city for this contact. The field is nullable |
| state | String | The state for this contact. The field is nullable |
| postal | String | The postal code for this contact. The field is nullable |
| country | String | The country for this contact. The field is nullable |
| notes | String | Free form text notes entered by end users for the contact. The field is nullable |
| tags | Array of String | When present represents a collection of tags use for applying ad-hoc categorization and collation of contacts. The field is nullable |
| status | String | The status of the contact. Valid values are pending_contact, active_lead, client and none. |
| created_at | Datetime | The date and time which this contact was created. |
| archived_at | Datetime | The date and time which this contact was archived. The field is nullable |
Chat Object
Chat Lead Event
{
"lead": {
"campaign_id": 350851,
"master_campaign_id": "2705608",
"campaign_name": "Orange Paper",
"id": 1632500,
"created_at": "2021-07-30T15:54:30Z",
"occured_at": "2021-07-30T15:54:28Z",
"tags": [
"Form Lead",
"Orange Paper"
],
"event_type": "form",
"contact_id": 1414924,
"status": "pending_contact",
"display_name": "Adam Smith",
"contact": {
"status": "pending_contact",
"id": 1414924,
"created_at": "2021-07-30T15:38:55Z",
"tags": [
"Orange Paper"
],
"first_name": "Adam",
"last_name": "Smith",
"email": "a.smith@tattoine.net",
"company": "",
"phone_mobile": "",
"phone_work": "612-867-5309",
"address1": "Ocean drive",
"address2": "",
"city": "",
"state": "",
"postal": "",
"country": ""
},
"chat": {
"summary": "Ronita \nNo\nOn campus \nDo your college offer medical billing?\nYes. \nRonita Wade and my number 8627049412; email: ronitawade7075@hotmail.com\nNewark, NJ\nThe Belleville location would be better for me. \nIt would be better in September. \nYes\nOk\nThank You, Jennifer but they don’t have medical billing. ",
"transcript": [
{
"id": 1,
"timestamp": "5/10/2021 2:05:06 PM",
"from": "Jennifer:",
"message": "Hello, thanks for contacting Eastern International College. My name is Jennifer, may I have your name?"
},
{
"id": 2,
"timestamp": "5/10/2021 2:05:23 PM",
"from": "Visitor:",
"message": "Ronita"
},
{
"id": 3,
"timestamp": "5/10/2021 2:05:40 PM",
"from": "Jennifer:",
"message": "Hi, Ronita. Have you contacted Eastern International College before?"
},
{
"id": 4,
"timestamp": "5/10/2021 2:05:46 PM",
"from": "Visitor:",
"message": "No"
},
{
"id": 5,
"timestamp": "5/10/2021 2:05:52 PM",
"from": "Jennifer:",
"message": "Good to have you with us. Are you interested in online or on-campus program?"
},
{
"id": 6,
"timestamp": "5/10/2021 2:06:05 PM",
"from": "Visitor:",
"message": "On campus"
},
{
"id": 7,
"timestamp": "5/10/2021 2:06:07 PM",
"from": "Jennifer:",
"message": "Okay. Which of our programs are you interested in?"
},
{
"id": 8,
"timestamp": "5/10/2021 2:06:22 PM",
"from": "Visitor:",
"message": "Do your college offer medical billing?"
},
{
"id": 9,
"timestamp": "5/10/2021 2:06:57 PM",
"from": "Jennifer:",
"message": "Alright. One of our Admissions Representatives can discuss this in greater detail. May I have your first and last name along with your phone number and email to better assist you?"
},
{
"id": 10,
"timestamp": "5/10/2021 2:07:31 PM",
"from": "Visitor:",
"message": "Yes."
},
{
"id": 11,
"timestamp": "5/10/2021 2:08:36 PM",
"from": "Visitor:",
"message": "Ronita Wade and my number 862-704-9412; email: ronitawade7075@hotmail.com"
},
{
"id": 12,
"timestamp": "5/10/2021 2:08:42 PM",
"from": "Jennifer:",
"message": "Thank you for the contact information, Ronita. Which city and state are you located in?"
},
{
"id": 13,
"timestamp": "5/10/2021 2:09:09 PM",
"from": "Visitor:",
"message": "Newark, NJ"
},
{
"id": 14,
"timestamp": "5/10/2021 2:09:35 PM",
"from": "Jennifer:",
"message": "Great. Which of our locations are you interested in attending Jersey City or Belleville location?"
},
{
"id": 15,
"timestamp": "5/10/2021 2:10:08 PM",
"from": "Visitor:",
"message": "The Belleville location would be better for me."
},
{
"id": 16,
"timestamp": "5/10/2021 2:10:17 PM",
"from": "Jennifer:",
"message": "Okay. How soon are you interested in enrolling?"
},
{
"id": 17,
"timestamp": "5/10/2021 2:11:06 PM",
"from": "Visitor:",
"message": "It would be better in September."
},
{
"id": 18,
"timestamp": "5/10/2021 2:11:20 PM",
"from": "Jennifer:",
"message": "Sounds good! For further assistance, I can connect you directly to our office by phone using our Call Connect service. Would you like to speak with someone now?"
},
{
"id": 19,
"timestamp": "5/10/2021 2:11:53 PM",
"from": "Visitor:",
"message": "Yes"
},
{
"id": 20,
"timestamp": "5/10/2021 2:12:23 PM",
"from": "Jennifer:",
"message": "Perfect. One moment please, I'm attempting to connect you now (please be aware that, for routing purposes, your caller ID will show a 925 area code). Please pick up and wait to be connected. I will be here if you need anything."
},
{
"id": 21,
"timestamp": "5/10/2021 2:12:48 PM",
"from": "Visitor:",
"message": "Ok"
},
{
"id": 22,
"timestamp": "5/10/2021 2:13:29 PM",
"from": "Jennifer:",
"message": "You should now be connected. Is there anything else I can help you with?"
},
{
"id": 23,
"timestamp": "5/10/2021 2:15:43 PM",
"from": "Visitor:",
"message": "Thank You, Jennifer but they don’t have medical billing."
},
{
"id": 24,
"timestamp": "5/10/2021 2:16:06 PM",
"from": "Jennifer:",
"message": "You are welcome. Thank you for contacting Eastern International College. Have a nice day, Ronita!"
}
]
}
}
| Field | Type | Description |
|---|---|---|
| summary | String | A freeform text description of the chat. The field is nullable |
| transcript | Array of ChatTranscripts | An ordered array of chat transcript objects. |
ChatTranscript Object
| Field | Type | Description |
|---|---|---|
| id | Integer | A sequential id of the line chat transcript. It uniquely identifies a line of the chat transcript within this lead event. |
| timestamp | String | The date and time that the external chat API registered for this line of the chat transcript. |
| from | String | The display name of the member of the chat who sent this message. |
| message | String | The message body of this line of the chat transcript. |
Call Object
Call Lead Event
{
"campaign_id": 357509,
"master_campaign_id": "2927264",
"campaign_name": "Management Service | Eastern International College",
"id": 136294964,
"created_at": "2021-05-10T16:12:08-05:00",
"occured_at": "2021-05-10T16:07:51-05:00",
"tags": [
"Call Lead",
"Management Service | Eastern International College"
],
"event_type": "call",
"contact_id": 36996224,
"status": "pending_contact",
"display_name": "Bolanos, Kelly ",
"contact": {
"status": "pending_contact",
"id": 36996224,
"created_at": "2018-09-12T15:35:36-05:00",
"tags": [
"Direct Site Traffic",
"Management Service | Eastern International College",
"Organic Search"
],
"first_name": "Kelly ",
"last_name": "Bolanos",
"email": "bolanoskelly@gmail.com",
"phone_work": "9738611219",
"postal": "07011",
"company": "Eastern International College",
"city": "",
"state": ""
},
"call": {
"occured_at": "2021-05-10T16:07:51-05:00",
"recording_url": "https://webservice.telmetrics.com/filedownload.ashx/4fcbd064-840d-4690-935c-71be733f68a4/2179874818.mp3",
"duration": "03:47"
}
}
| Field | Type | Description |
|---|---|---|
| occured_at | Datetime | The date and time that the call occurred. |
| duration | Integer | The duration of the call in seconds. |
| recording_url | String | The URL address to an audio recording of the call. |
Form Object
Form Lead Event
{
"lead":{
"id":21,
"contact_id":21,
"campaign_id":3,
"archived_at":null,
"created_at":"2017-05-30T08:56:05.000-07:00",
"important_at":null,
"occured_at":"2017-05-30T08:15:05.000-07:00",
"read_at":"2017-06-06T11:32:48-07:00",
"event_type":"form",
"campaign_name":"Campaign",
"status":"none",
"notes":"Free form event notes",
"tags":[
"bar",
"baz",
"foo",
"Campaign"
],
"contact":{
"id":217,
"first_name":"Harry",
"last_name":"Brown",
"title":"Dr.",
"email":"slim.gleason@heatotekuhic.com",
"company":"Group",
"tags":[
"nothing",
"Campaign"
],
"notes":"Some contact free form notes",
"archived_at":null,
"created_at":"2017-05-30T08:56:05.000-07:00",
"status":"none",
"phone_fax":null,
"phone_home":"812-666-3948",
"phone_mobile":"(699)385-8032",
"phone_work":"379-420-69",
"address1":null,
"address2":null,
"city":null,
"state":null,
"postal":null,
"country":null
},
"form":{
"sub_type":"FormPost",
"full_message":"Subject:\nLabore vel iusto dicta quidem.\n\nMessage:\nEt modi animi ex ut non enim. Voluptate sit laborum qui voluptatum similique ut praesentium. Ut vel dicta totam.",
"subject":"Labore vel iusto dicta quidem.",
"message":"Et modi animi ex ut non enim. Voluptate sit laborum qui voluptatum similique ut praesentium. Ut vel dicta totam.",
"extra_fields":{
"slogan":"Exclusive object-oriented time-frame",
"SomeCustomField":"Eaque enim qui labore occaecati distinctio.",
"another_custom_field":"Aut saepe quidem aut repudiandae soluta."
}
}
}
}
Email Lead Event
{
"lead": {
"campaign_id": 350851,
"master_campaign_id": "2705608",
"campaign_name": "Orange Paper",
"id": 1632500,
"created_at": "2021-07-30T15:54:30Z",
"occured_at": "2021-07-30T15:54:28Z",
"tags": [
"Form Lead",
"Orange Paper"
],
"event_type": "form",
"contact_id": 1414924,
"status": "pending_contact",
"display_name": "Adam Smith",
"contact": {
"status": "pending_contact",
"id": 1414924,
"created_at": "2021-07-30T15:38:55Z",
"tags": [
"Orange Paper"
],
"first_name": "Adam",
"last_name": "Smith",
"email": "a.smith@tattoine.net",
"company": "",
"phone_mobile": "",
"phone_work": "612-867-5309",
"address1": "Ocean drive",
"address2": "",
"city": "",
"state": "",
"postal": "",
"country": ""
},
"form": {
"sub_type": "FormEmail",
"full_message": "Message:\nLorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod\ntempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam,\nquis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo\nconsequat. Duis aute irure dolor in reprehenderit in voluptate velit esse\ncillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non\nproident, sunt in culpa qui officia deserunt mollit anim id est laborum.",
"message": "Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod\ntempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam,\nquis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo\nconsequat. Duis aute irure dolor in reprehenderit in voluptate velit esse\ncillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non\nproident, sunt in culpa qui officia deserunt mollit anim id est laborum.",
"extra_fields": {
"campaign_id": "USA_2705608",
"campaign_name": "Orange Paper",
"submit_button": "SUBMIT",
"name": "Adam Smith",
"phone": "6128675309",
"email": "Adam@example.com",
"address": "",
"address1": "",
"postal": "",
"country": "",
"company": "",
"message": "Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod\ntempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam,\nquis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo\nconsequat. Duis aute irure dolor in reprehenderit in voluptate velit esse\ncillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non\nproident, sunt in culpa qui officia deserunt mollit anim id est laborum."
}
}
}
}
| Field | Type | Description |
|---|---|---|
| sub_type | String | The subtype of the form. Valid values are FormPost and FormEmail. |
| full_message | String | The full form message |
| subject | String | Subject The field is nullable |
| extra_fields | Array of String | extra fields The field is nullable |
Lead Metric APIs
Marketing Activity
Resource Overview
| Method | URI Format |
|---|---|
| GET | /client_reports/marketing_activity/[gmaid]?[query_params] |
Use GET to retrieve information from the Marketing activity API. Data can be returned for a GMAID by a specific date range determined by start date and end date.
Subtotals can be further aggregated given an interval, and will be totaled for day, calendar_week, or calendar_month. The first day of the interval will be used to denote the interval totals.
Use the master_campaign_id parameter to limit the results to a single Master Campaign ID.
Parameters
When using the GET method, the results can be filtered using these parameters:
| Param | Required | Function |
|---|---|---|
| start_date | Yes | Restricts the results to those occurring on or after this date |
| end_date | Yes | Restricts the results to those occurring on or before this date |
| gmaid | Yes | Restrict results to the specified Global Master Advertiser ID |
| global_master_campaign_id[] | No | Restrict results to the specified master campaign id |
| interval_size | No | Return subtotals for the given intervals within the start-end time provided. Accepts calendar_month, calendar_week, or day (Default is day) |
Response Data Details
Retrieve data for a specific range of dates
curl -H "Authorization: Bearer OAUTH_ACCESS_TOKEN" \
https://api.localiqservices.com/client_reports/marketing_activity/TEST_1?start_date=2019-10-01&end_date=2020-02-25'
Retrieve data for a specific master campaign id
curl -H "Authorization: Bearer OAUTH_ACCESS_TOKEN" \
https://api.localiqservices.com/client_reports/marketing_activity/TEST_1?start_date=2019-10-01&end_date=2020-02-25&global_master_campaign_id[]=TEST_1' \
Retrieve data for a specific range of dates grouped by calendar week
curl -H "Authorization: Bearer OAUTH_ACCESS_TOKEN" \
https://api.localiqservices.com/client_reports/marketing_activity/TEST_1?start_date=2019-10-01&end_date=2020-02-25&interval_size=calendar_week' \
Retrieve data with all options together with results below
curl -H "Authorization: Bearer OAUTH_ACCESS_TOKEN" \
https://api.localiqservices.com/client_reports/marketing_activity/TEST_1?start_date=2019-10-01&end_date=2020-02-25&global_master_campaign_id[]=TEST_1&interval_size=calendar_week' \
Example Response
{
"api_name": "marketing_activity",
"api_run_date": "2021-10-25",
"start_date": "2021-05-22",
"end_date": "2021-05-25",
"time_zone": "America/Los_Angeles",
"interval_size": "day",
"report_data": {
"campaigns": [
{
"global_master_campaign_id": "USA_3212412",
"campaign_name": "SK | Slipknot Group | Heavy Metal",
"campaign_type": "search",
"organization": "reachlocal",
"offer_id": 2101,
"source": "XMO",
"campaign_start_date": "2021-05-24",
"campaign_end_date": "2021-06-24",
"intervals": [
{
"start_date": "2021-05-24",
"bookings": 7,
"sms": 2,
"visits": 6,
"chats": 0,
"calls": 0,
"forms": 0,
"channels": {
"search": {
"bookings": 3,
"sms": 2,
"visits": 5,
"chats": 0,
"calls": 0,
"forms": 0
},
"social": {
"bookings": 0,
"sms": 0,
"visits": 1,
"chats": 0,
"calls": 0,
"forms": 0
}
}
}
],
"totals": {
"total_bookings": 3,
"total_sms": 0,
"total_visits": 12,
"total_calls": 0,
"total_chats": 0,
"total_forms": 0
}
}
],
"search": {
"intervals": [
{
"start_date": "2021-05-22",
"bookings": 0,
"sms": 0,
"visits": 0,
"chats": 1,
"calls": 0,
"forms": 1
}
],
"totals": {
"total_bookings": 0,
"total_sms": 0,
"total_visits": 0,
"total_calls": 0,
"total_chats": 1,
"total_forms": 1
}
},
"social": {
"intervals": [],
"totals": {
"total_bookings": 0,
"total_sms": 0,
"total_visits": 0,
"total_calls": 0,
"total_chats": 0,
"total_forms": 0
}
},
"direct": {
"intervals": [
{
"start_date": "2021-05-22",
"bookings": 0,
"sms": 0,
"visits": 28,
"chats": 0,
"calls": 0,
"forms": 0
},
{
"start_date": "2021-05-23",
"bookings": 0,
"sms": 0,
"visits": 9,
"chats": 0,
"calls": 0,
"forms": 0
},
{
"start_date": "2021-05-24",
"bookings": 0,
"sms": 0,
"visits": 16,
"chats": 0,
"calls": 0,
"forms": 0
}
],
"totals": {
"total_bookings": 0,
"total_sms": 0,
"total_visits": 53,
"total_calls": 0,
"total_chats": 0,
"total_forms": 0
}
},
"shopping": {
"intervals": [
{
"start_date": "2021-05-22",
"bookings": 0,
"sms": 0,
"visits": 28,
"chats": 0,
"calls": 0,
"forms": 0
},
{
"start_date": "2021-05-23",
"bookings": 0,
"sms": 0,
"visits": 9,
"chats": 0,
"calls": 0,
"forms": 0
},
{
"start_date": "2021-05-24",
"bookings": 0,
"sms": 0,
"visits": 16,
"chats": 0,
"calls": 0,
"forms": 0
}
],
"totals": {
"total_bookings": 0,
"total_sms": 0,
"total_visits": 53,
"total_calls": 0,
"total_chats": 0,
"total_forms": 0
}
},
"video": {
"intervals": [
{
"start_date": "2021-05-22",
"bookings": 0,
"sms": 0,
"visits": 28,
"chats": 0,
"calls": 0,
"forms": 0
},
{
"start_date": "2021-05-23",
"bookings": 0,
"sms": 0,
"visits": 9,
"chats": 0,
"calls": 0,
"forms": 0
},
{
"start_date": "2021-05-24",
"bookings": 0,
"sms": 0,
"visits": 16,
"chats": 0,
"calls": 0,
"forms": 0
}
],
"totals": {
"total_bookings": 0,
"total_sms": 0,
"total_visits": 53,
"total_calls": 0,
"total_chats": 0,
"total_forms": 0
}
},
"directory": {
"intervals": [],
"totals": {
"total_bookings": 0,
"total_sms": 0,
"total_visits": 0,
"total_calls": 0,
"total_chats": 0,
"total_forms": 0
}
},
"marketplace": {
"intervals": [],
"totals": {
"total_bookings": 0,
"total_sms": 0,
"total_visits": 0,
"total_calls": 0,
"total_chats": 0,
"total_forms": 0
}
},
"other": {
"intervals": [],
"totals": {
"total_bookings": 0,
"total_sms": 0,
"total_visits": 0,
"total_calls": 0,
"total_chats": 0,
"total_forms": 0
}
},
"otherpaid": {
"intervals": [],
"totals": {
"total_bookings": 0,
"total_sms": 0,
"total_visits": 0,
"total_calls": 0,
"total_chats": 0,
"total_forms": 0
}
},
"totals": {
"total_bookings": 0,
"total_sms": 2,
"total_visits": 79,
"total_calls": 0,
"total_chats": 1,
"total_forms": 0
}
},
"global_master_advertiser_id": "USA_136048"
}
| Field Name | Datatype | Description |
|---|---|---|
| api_name | String | Name of the API |
| api_run_date | String | Date report was run |
| start_date | String | Start date of report |
| end_date | String | End date of report |
| time_zone | String | Time Zone |
| interval_size | String | Interval Size ('none', 'day', 'calendar_week' or 'calendar_month') |
| report_data | Report Data Object | Report details |
| global_master_advertiser_id | String | Global Master Advertiser ID |
| Field Name | Datatype | Description |
|---|---|---|
| campaigns | Campaigns Object | chat counts for chats attributed to paid campaigns |
| search | Search Object | chat, booking, visit, call, form counts attributed to organic search sources |
| social | Social Object | chat, booking, visit, call, form counts attributed to organic social sources |
| direct | Direct Object | chat, booking, visit, call, form counts attributed to organic direct sources |
| directory | Directory Object | chat, booking, visit, call, form counts attributed to organic directory sources |
| marketplace | Marketplace Object | chat, booking, visit, call, form counts attributed to marketplace sources |
| other | Other Object | chat, booking, visit, call, form counts attributed to other organic sources |
| otherpaid | Otherpaid Object | chat, booking, visit, call, form counts attributed to organic sources |
| totals | Totals Object | Totals of vists, calls, bookings, chats and forms for each type |
| Field Name | Datatype | Description |
|---|---|---|
| global_master_campaign_id | String | Identifier for campaign |
| campaign_name | String | Name of campaign |
| campaign_type | String | Type of campaign |
| campaign_status | String | Status of campaign |
| organization | String | Organization |
| offer_id | String | Offer id of the campaign |
| source | String | Source of the campaign |
| campaign_start_date | String | Start date of campaign |
| campaign_end_date | String | End date of campaign |
| intervals | Intervals Object | Data for specified interval |
| totals | Totals Object | Totals of vists, calls, bookings, chats and forms for each type |
| Field Name | Datatype | Description |
|---|---|---|
| intervals | Intervals Object | Data for specified interval |
| totals | Totals Object | Totals of vists, calls, bookings, chats and forms for each type |
| Field Name | Datatype | Description |
|---|---|---|
| intervals | Intervals Object | Data for specified interval |
| totals | Totals Object | Totals of vists, calls, bookings, chats and forms for each type |
| Field Name | Datatype | Description |
|---|---|---|
| intervals | Intervals Object | Data for specified interval |
| totals | Totals Object | Totals of vists, calls, bookings, chats and forms for each type |
| Field Name | Datatype | Description |
|---|---|---|
| intervals | Intervals Object | Data for specified interval |
| totals | Totals Object | Totals of vists, calls, bookings, chats and forms for each type |
Marketplace Object (Deprecated)
| Field Name | Datatype | Description |
|---|---|---|
| intervals | Intervals Object | Data for specified interval |
| totals | Totals Object | Totals of vists, calls, bookings, chats and forms for each type |
| Field Name | Datatype | Description |
|---|---|---|
| intervals | Intervals Object | Data for specified interval |
| totals | Totals Object | Totals of vists, calls, bookings, chats and forms for each type |
| Field Name | Datatype | Description |
|---|---|---|
| intervals | Intervals Object | Data for specified interval |
| totals | Totals Object | Totals of vists, calls, bookings, chats and forms for each type |
| Field Name | Datatype | Description |
|---|---|---|
| start_date | String | Start date of interval |
| bookings | Integer | Number of total bookings |
| visits | Integer | Number of total visits |
| chats | Integer | Number of total chat |
| calls | Integer | Number of total calls |
| forms | Integer | Number of total forms and emails |
| Field Name | Datatype | Description |
|---|---|---|
| total_bookings | Integer | Number of total bookings |
| total_visits | Integer | Number of total visits |
| total_calls | Integer | Number of total calls |
| total_chats | Integer | Number of total chats |
| total_forms | Integer | Number of total forms |
Chat Summary
Resource Overview
| Method | URI Format |
|---|---|
| GET | /client_reports/chat_summary/[gmaid]?[query_params] |
This API can be used by customers who have our chat widget on their site. The API has metrics on each chat along with traffic information (Paid Campaign/Organic/Otherpaid).
Use GET to retrieve information from the Chat Summary API. Data can be returned for a GMAID by a specific date range determined by start date and end date.
Subtotals will be returned for each Master Campaign ID with chat activity in the specified date range.
Subtotals can be further aggregated given an interval, and will be totaled for day, calendar_week, or calendar_month. The first day of the interval will be used to denote the interval totals.
Use the master_campaign_id parameter to limit the results to a single Master Campaign ID.
Parameters
When using the GET method, the results can be filtered using these parameters:
| Param | Required | Function |
|---|---|---|
| start_date | Yes | Restricts the results to those occurring on or after this date |
| end_date | Yes | Restricts the results to those occurring on or before this date |
| gmaid | Yes | Restrict results to the specified Global Master Advertiser ID |
| global_master_campaign_id[] | No | Restrict results to the specified master campaign id |
| interval_size | No | Return subtotals for the given intervals within the start-end time provided. Accepts calendar_month, calendar_week, or day (Default is day) |
Response Data Details
Retrieve data for a specific range of dates
curl -H "Authorization: Bearer OAUTH_ACCESS_TOKEN" \
https://api.localiqservices.com/client_reports/chat_summary/TEST_1?start_date=2019-10-01&end_date=2020-02-25'
Retrieve data for a specific master campaign id
curl -H "Authorization: Bearer OAUTH_ACCESS_TOKEN" \
https://api.localiqservices.com/client_reports/chat_summary/TEST_1?start_date=2019-10-01&end_date=2020-02-25&global_master_campaign_id[]=TEST_1' \
Retrieve data for a specific range of dates grouped by calendar week
curl -H "Authorization: Bearer OAUTH_ACCESS_TOKEN" \
https://api.localiqservices.com/client_reports/chat_summary/TEST_1?start_date=2019-10-01&end_date=2020-02-25&interval_size=calendar_week' \
Retrieve data with all options together with results below
curl -H "Authorization: Bearer OAUTH_ACCESS_TOKEN" \
https://api.localiqservices.com/client_reports/chat_summary/TEST_1?start_date=2019-10-01&end_date=2020-02-25&global_master_campaign_id[]=TEST_1&interval_size=calendar_week' \
Example Response
{
"api_name": "chat_summary",
"api_run_date": "2020-10-16",
"start_date": "2020-10-10",
"end_date": "2020-10-10",
"time_zone": "America/Los_Angeles",
"interval_size": "none",
"currency": "USD",
"report_data": {
"campaigns": [
{
"global_master_campaign_id": "TEST_691177",
"campaign_name": "Display Campaign (Demo)",
"campaign_type": "display",
"campaign_status": "running",
"organization": "reachlocal",
"campaign_start_date": "2020-01-01",
"campaign_end_date": null,
"intervals": [
{
"start_date": "2020-10-10",
"non_lead_chats": 0,
"total_chats": 7,
"chat_leads": 7,
"chat_sales": 7,
"chat_service": 0,
"chat_other": 0,
"call_connect": 0
}
]
},
{
"global_master_campaign_id": "TEST_691180",
"campaign_name": "Search Campaign (Demo)",
"campaign_type": "search",
"campaign_status": "running",
"organization": "reachlocal",
"campaign_start_date": "2020-01-01",
"campaign_end_date": null,
"intervals": [
{
"start_date": "2020-10-10",
"non_lead_chats": 0,
"total_chats": 10,
"chat_leads": 10,
"chat_sales": 10,
"chat_service": 0,
"chat_other": 0,
"call_connect": 0
}
]
},
{
"global_master_campaign_id": "TEST_691183",
"campaign_name": "Totaltrack Phone Campaign (Demo)",
"campaign_type": "totaltrack_phone",
"campaign_status": "running",
"organization": "reachlocal",
"campaign_start_date": "2020-01-01",
"campaign_end_date": null,
"intervals": [
{
"start_date": "2020-10-10",
"non_lead_chats": 0,
"total_chats": 9,
"chat_leads": 9,
"chat_sales": 9,
"chat_service": 0,
"chat_other": 0,
"call_connect": 0
}
]
},
{
"global_master_campaign_id": "TEST_691187",
"campaign_name": "Totaltrack Web Phone Campaign (Demo)",
"campaign_type": "totaltrack_web_phone",
"campaign_status": "running",
"organization": "reachlocal",
"campaign_start_date": "2020-01-01",
"campaign_end_date": null,
"intervals": [
{
"start_date": "2020-10-10",
"non_lead_chats": 0,
"total_chats": 5,
"chat_leads": 5,
"chat_sales": 5,
"chat_service": 0,
"chat_other": 0,
"call_connect": 0
}
]
},
{
"global_master_campaign_id": "TEST_691190",
"campaign_name": "Totaltrack Web Campaign (Demo)",
"campaign_type": "totaltrack_web",
"campaign_status": "running",
"organization": "reachlocal",
"campaign_start_date": "2020-01-01",
"campaign_end_date": null,
"intervals": [
{
"start_date": "2020-10-10",
"non_lead_chats": 0,
"total_chats": 7,
"chat_leads": 7,
"chat_sales": 7,
"chat_service": 0,
"chat_other": 0,
"call_connect": 0
}
]
},
{
"global_master_campaign_id": "TEST_691195",
"campaign_name": "Other Campaign (Demo)",
"campaign_type": "other",
"campaign_status": "running",
"organization": "reachlocal",
"campaign_start_date": "2020-01-01",
"campaign_end_date": null,
"intervals": [
{
"start_date": "2020-10-10",
"non_lead_chats": 0,
"total_chats": 6,
"chat_leads": 6,
"chat_sales": 6,
"chat_service": 0,
"chat_other": 0,
"call_connect": 0
}
]
},
{
"global_master_campaign_id": "TEST_691205",
"campaign_name": "Chat Campaign (Demo)",
"campaign_type": "chat",
"campaign_status": "running",
"organization": "reachlocal",
"campaign_start_date": "2020-01-01",
"campaign_end_date": null,
"intervals": [
{
"start_date": "2020-10-10",
"non_lead_chats": 0,
"total_chats": 9,
"chat_leads": 9,
"chat_sales": 9,
"chat_service": 0,
"chat_other": 0,
"call_connect": 0
}
]
},
{
"global_master_campaign_id": "TEST_691211",
"campaign_name": "Facebook Campaign (Demo)",
"campaign_type": "display",
"campaign_status": "running",
"organization": "reachlocal",
"campaign_start_date": "2020-01-01",
"campaign_end_date": null,
"intervals": [
{
"start_date": "2020-10-10",
"non_lead_chats": 0,
"total_chats": 8,
"chat_leads": 8,
"chat_sales": 8,
"chat_service": 0,
"chat_other": 0,
"call_connect": 0
}
]
},
{
"global_master_campaign_id": "TEST_691217",
"campaign_name": "Geofence Campaign (Demo)",
"campaign_type": "display",
"campaign_status": "running",
"organization": "reachlocal",
"campaign_start_date": "2020-01-01",
"campaign_end_date": null,
"intervals": [
{
"start_date": "2020-10-10",
"non_lead_chats": 0,
"total_chats": 6,
"chat_leads": 6,
"chat_sales": 6,
"chat_service": 0,
"chat_other": 0,
"call_connect": 0
}
]
},
{
"global_master_campaign_id": "TEST_691223",
"campaign_name": "Youtube Campaign (Demo)",
"campaign_type": "display",
"campaign_status": "running",
"organization": "reachlocal",
"campaign_start_date": "2020-01-01",
"campaign_end_date": null,
"intervals": [
{
"start_date": "2020-10-10",
"non_lead_chats": 0,
"total_chats": 8,
"chat_leads": 8,
"chat_sales": 8,
"chat_service": 0,
"chat_other": 0,
"call_connect": 0
}
]
},
{
"global_master_campaign_id": "TEST_691233",
"campaign_name": "Xmedia Campaign (Demo)",
"campaign_type": "xmedia",
"campaign_status": "running",
"organization": "reachlocal",
"campaign_start_date": "2020-01-01",
"campaign_end_date": null,
"intervals": [
{
"start_date": "2020-10-10",
"non_lead_chats": 0,
"total_chats": 5,
"chat_leads": 5,
"chat_sales": 5,
"chat_service": 0,
"chat_other": 0,
"call_connect": 0
}
]
},
{
"global_master_campaign_id": "TEST_691233",
"campaign_name": "Targeted Email Campaign (Demo)",
"campaign_type": "email",
"campaign_status": "running",
"organization": "reachlocal",
"campaign_start_date": "2020-01-01",
"campaign_end_date": null,
"intervals": [
{
"start_date": "2020-10-10",
"non_lead_chats": 0,
"total_chats": 11,
"chat_leads": 11,
"chat_sales": 11,
"chat_service": 0,
"chat_other": 0,
"call_connect": 0
}
]
}
],
"organic": {
"intervals": [
{
"start_date": "2020-10-10",
"non_lead_chats": 0,
"total_chats": 0,
"chat_leads": 0,
"chat_sales": 0,
"chat_service": 0,
"chat_other": 0,
"call_connect": 0
}
]
},
"otherpaid": {
"intervals": [
{
"start_date": "2020-10-11",
"non_lead_chats": 0,
"total_chats": 0,
"chat_leads": 0,
"chat_sales": 0,
"chat_service": 0,
"chat_other": 0,
"call_connect": 0
}
]
}
},
"global_master_advertiser_id": "TEST_1"
}
| Field Name | Datatype | Description |
|---|---|---|
| api_name | String | Name of the API |
| api_run_date | String | Date report was run |
| start_date | String | Start date of report |
| end_date | String | End date of report |
| time_zone | String | Time Zone |
| interval_size | String | Interval Size ('none', 'day', 'calendar_week' or 'calendar_month') |
| currency | String | Currency Type of Monetary Values Returned in Report (Example: USD, AUD, CAD) |
| report_data | Object | Report details. Report Data Object |
| global_master_advertiser_id | String | Global Master Advertiser ID |
| Field Name | Datatype | Description |
|---|---|---|
| campaigns | Object | chat counts for chats attributed to paid campaigns. Campaigns Object |
| organic | Object | chat counts for chats attributed to organic sources (Organic search, Direct Site Traffic, etc.) Organic Object |
| otherpaid | Object | chat counts for chats attributed to paid traffic by other media vendors. Otherpaid Object |
| Field Name | Datatype | Description |
|---|---|---|
| global_master_campaign_id | String | Identifier for campaign |
| campaign_name | String | Name of campaign |
| campaign_type | String | Type of campaign |
| campaign_status | String | Status of campaign |
| organization | String | Organization |
| campaign_start_date | String | Start date of campaign |
| campaign_end_date | String | End date of campaign |
| intervals | Object | Data for specified interval. Intervals Object |
| Field Name | Datatype | Description |
|---|---|---|
| intervals | Object | Data for specified interval. Intervals Object |
| Field Name | Datatype | Description |
|---|---|---|
| start_date | String | Start date of interval |
| non_lead_chats | Integer | Number of non-lead chats, has no email address or phone number to create a Contact |
| total_chats | Integer | Number of total chats, includes non lead chats |
| chat_leads | Integer | Number of chat leads, excludes non lead chats |
| chat_sales | Integer | Number of chats marked as 'sales' |
| chat_service | Integer | Number of chats marked as 'service' |
| chat_other | Integer | Number of chats marked as 'other' |
| call_connect | Integer | Subset of chats that initiated a call connect |
| Field Name | Datatype | Description |
|---|---|---|
| intervals | Object | Data for specified interval. Intervals Object |
| Field Name | Datatype | Description |
|---|---|---|
| start_date | String | Start date of interval |
| non_lead_chats | Integer | Number of non-lead chats, has no email address or phone number to create a Contact |
| total_chats | Integer | Number of total chats, includes non lead chats |
| chat_leads | Integer | Number of chat leads, excludes non lead chats |
| chat_sales | Integer | Number of chats marked as 'sales' |
| chat_service | Integer | Number of chats marked as 'service' |
| chat_other | Integer | Number of chats marked as 'other' |
| call_connect | Integer | Subset of chats that initiated a call connect |
Lead Details
Resource Overview
| Method | URI Format |
|---|---|
| GET | /client_reports/lead_detail/[gmaid]?[query_params] |
Use GET to retrieve information for the Lead Details report for a given advertiser.
The report will contains calls, emails, web events, and chats broken down by day or month. It will also contain the number of calls broken down by call duration. A total section will contain all the calls, unique calls, calls connected, average call length, emails, web events, chats and leads for the date range specified. Finally, the report will have a break down for calls by hour for each day of the week.
Parameters
When using the GET method, the results can be filtered using these parameters:
| Param | Function |
|---|---|
| start_date | Restricts the results to those occurring on or after this date |
| end_date | Restricts the results to those occurring on or before this date |
| global_master_campaign_id[] | Restrict results to one or more specific campaigns. This should be a comma separated string. Ex: global_master_campaign_id[]=TEST_1,TEST_2 |
| campaign_status[] | Restrict results to all campaigns with given status values. Allowed values are running, stopped and ended. This should be a comma separated string. Ex: campaign_status[]=running,stopped |
| campaign_cycle | Restrict results to a single campaign cycle |
| interval_size | Use calendar_month or calendar_week to roll up the data points into calendar intervals (default is 1 day per interval) |
To specify a date range:
- Specify start_date and end_date.
- When specifying a campaign_cycle, do not use date range params.
Response Data Details
Retrieve data for a specific range of dates
curl -H "Authorization: Bearer OAUTH_ACCESS_TOKEN" \
https://api.localiqservices.com/client_reports/lead_detail/TEST_1?start_date=2016-12-01&end_date=2016-12-31
Retrieve data for a specific campaign starting on a certain date
curl -g -H "Authorization: Bearer OAUTH_ACCESS_TOKEN" \
https://api.localiqservices.com/client_reports/lead_detail/TEST_1?global_master_campaign_id[]=TEST_1&start_date=2016-10-01&end_date=2016-12-31
Retrieve data for a specific campaign cycle
curl -H "Authorization: Bearer OAUTH_ACCESS_TOKEN" \
https://api.localiqservices.com/client_reports/lead_detail/TEST_1?campaign_cycle=TEST_1
Retrieve data for campaigns that are stopped and running
curl -g -H "Authorization: Bearer OAUTH_ACCESS_TOKEN" \
https://api.localiqservices.com/client_reports/lead_detail/TEST_1?&campaign_status[]=running,stopped&start_date=2016-10-01&end_date=2016-12-31
Example Response
{
"report_type": "lead_detail",
"report_date": "2020-10-15",
"earliest_date_available": "2020-01-01",
"start_date": "2020-10-10",
"end_date": "2020-10-10",
"time_zone": "America/Los_Angeles",
"interval_size": "day",
"report_data": {
"totals_per_interval": [
{
"start_date": "2020-10-10",
"calls": 71,
"emails": 85,
"web_events": 86,
"qualified_web_events": 87,
"chats": 88
}
],
"call_duration": [
{
"duration": "0-29",
"total": 14
},
{
"duration": "30-59",
"total": 15
},
{
"duration": "60-119",
"total": 15
},
{
"duration": "120",
"total": 27
}
],
"calls_by_time_and_day": {
"saturday": {
"0": 2,
"1": 2,
"2": 3,
"3": 1,
"4": 2,
"5": 3,
"6": 3,
"7": 4,
"8": 2,
"9": 4,
"10": 3,
"11": 1,
"12": 2,
"13": 5,
"14": 3,
"15": 3,
"16": 2,
"17": 3,
"18": 2,
"19": 6,
"20": 6,
"21": 4,
"22": 3,
"23": 2
},
"max": 6
},
"totals": {
"calls": 71,
"unique_calls": 70,
"calls_connected": 70,
"average_call_length": 89.43,
"emails": 85,
"web_events": 86,
"qualified_web_events": 87,
"chats": 88,
"leads": 417
}
},
"global_master_advertiser_id": "TEST_1"
}
| Field Name | Datatype | Description |
|---|---|---|
| report_type | String | Type of report |
| report_date | String | Date report ran |
| earliest_date_available | String | How far back data is available |
| start_date | String | Start date of report |
| end_date | String | End date of report |
| time_zone | String | Time Zone |
| interval_size | String | Interval size for report |
| report_data | Object | Report Data Object. |
| global_master_advertiser_id | String | Identifier for advertiser |
| Field Name | Datatype | Description |
|---|---|---|
| totals_per_interval | Array | Lead totals broken down by day or month. Totals Per Interval Array. |
| call_duration | Array | Call duration data. ('duration' duration range in seconds, 'totals' total calls for duration) |
| totals | Object | Totals. Totals Object. |
| calls_by_time_and_day | Object | Call by hour by day. (day of week, hour of day) |
| Field Name | Datatype | Description |
|---|---|---|
| start_date | String | Start date for interval |
| calls | Integer | Calls for interval |
| emails | Integer | Emails for interval |
| web_events | Integer | Web events for interval |
| qualified_web_events | Integer | A lead generating CVT/Web Event |
| chats | Integer | Total chat generated by paid traffic for interval |
| Field Name | Datatype | Description |
|---|---|---|
| calls | Integer | Total calls |
| unique_calls | Integer | Total unique calls |
| calls_connected | Integer | Total calls connected |
| average_call_length | Integer | Total average call length |
| emails | Integer | Total emails |
| web_events | Integer | Total web events |
| qualified_web_events | Integer | A lead generating CVT/Web Event |
| chats | Integer | Total chat generated by paid traffic |
| leads | Integer | Total leads |
| Field Name | Datatype | Description |
|---|---|---|
| campaign_cycle | String | Identifier for cycle |
| start_date | String | Start date of cycle |
| end_date | String | End date of cycle |
| name | String | Name of cycle |
LSA Campaign Metrics
Resource Overview
| Method | URI Format |
|---|---|
| GET | /client_reports/google_local_service_ads/[gmaid]?[query_params] |
Use GET to retrieve the Local Service Ads Campaign Metrics report for a given advertiser.
The data returned will include rating_score, total_reviews, charged_leads, phone_calls and total_cost values organized by campaign.
Parameters
When using the GET method, the results can be filtered using these parameters:
| Param | Required | Function |
|---|---|---|
| start_date | Yes | Restricts the results to those ocurring on or after this date. |
| end_date | Yes | Restricts the results to those ocurring on or before this date. |
To specify a date range:
- Specify start_date and end_date.
Response Data Details
Retrieve data for advertiser and date range
curl -H "Authorization: Bearer OAUTH_ACCESS_TOKEN" \
https://api.localiqservices.com/client_reports/google_local_service_ads/TEST_1?start_date=2020-09-01&end_date=2020-09-02' \
Example Response
{
"report_type": "google_local_service_ads",
"report_date": "2020-09-10",
"start_date": "2020-09-01",
"end_date": "2020-09-02",
"currency": "USD",
"global_master_advertiser_id": "USA_5713",
"advertiser_name": "My Service Company",
"report_data": {
"campaigns": [
{
"name": "My Service Co LSA HVAC",
"global_master_campaign_id": "USA_77777777",
"start_date": "2020-04-30",
"end_date": "2020-06-04",
"type": "lsa",
"status": "ended",
"goals": [],
"weekly_budget": 461.0,
"intervals": [
{
"start_date": "2020-09-01",
"rating_score": 4.8,
"total_reviews": 192,
"charged_leads": 0,
"phone_calls": 1,
"total_cost": 0.0
},
{
"start_date": "2020-09-02",
"rating_score": 4.8,
"total_reviews": 192,
"charged_leads": 2,
"phone_calls": 2,
"total_cost": 50.0
}
]
},
{
"name": "My Service Co LSA Plumbing",
"global_master_campaign_id": "USA_88888888",
"start_date": "2020-04-30",
"end_date": "2020-06-04",
"type": "lsa",
"status": "ended",
"goals": [],
"weekly_budget": 461.0,
"intervals": [
{
"start_date": "2020-09-01",
"rating_score": 4.8,
"total_reviews": 192,
"charged_leads": 0,
"phone_calls": 1,
"total_cost": 0.0
},
{
"start_date": "2020-09-02",
"rating_score": 4.8,
"total_reviews": 192,
"charged_leads": 2,
"phone_calls": 2,
"total_cost": 50.0
}
]
}
]
}
}
| Field Name | Datatype | Description |
|---|---|---|
| api_name | String | Name of the API |
| api_run_date | String | Date report was run |
| start_date | String | Start date of report |
| end_date | String | End date of report |
| currency | String | Currency Type of Monetary Values Returned in Report (Example: USD, AUD, CAD) |
| global_master_advertiser_id | String | Global Master Advertiser ID |
| advertiser_name | String | Name of the Advertiser |
| report_data | Object | Report details. Report Data Object |
| Field Name | Datatype | Description |
|---|---|---|
| campaigns | Object | Data for specified campaign. Campaigns Object |
| Field Name | Datatype | Description |
|---|---|---|
| name | String | Name of campaign |
| global_master_campaign_id | String | Identifier for campaign |
| start_date | String | Start date of campaign |
| end_date | String | End date of campaign |
| type | String | Type of campaign |
| status | String | Status of campaign |
| goals | Object | Goals Object |
| weekly_budget | Decimal | Weekly Budget for the campaign |
| publisher_account_id | String | Identifier for the publisher account |
| intervals | Object | Data for specified interval. Intervals Object |
| Field Name | Datatype | Description |
|---|---|---|
| goal_type_id | String | Identifier for campaign goal type |
| goal_type | String | Name(Type) of goal type |
| Field Name | Datatype | Description |
|---|---|---|
| start_date | String | Start date of interval |
| rating_score | Decimal | Rating Score |
| total_reviews | Integer | Number numebr of Review |
| charged_leads | Integer | Number of charged leads |
| chat_sales | Integer | Number of Phone Calls |
| total_cost | Decimal | Total Cost |
LSA Campaign Metrics Rollup
Resource Overview
| Method | URI Format |
|---|---|
| GET | /leads/lsa_events/campaign_rollup?[query_params] |
Use GET to retrieve Local Service Ads metrics rolled up by camapgin for a given advertiser.
Parameters
When using the GET method, the results can be filtered using these parameters:
| Param | Required | Function |
|---|---|---|
| global_master_advertiser_id | Yes | Only leads for the specified advertiser will be returned. |
| start_date | Yes | Restricts the results to those ocurring on or after this date. |
| end_date | Yes | Restricts the results to those ocurring on or before this date. |
To specify a date range:
- Specify start_date and end_date.
Response Data Details
Retrieve data for advertiser and date range
curl -H "Authorization: Bearer OAUTH_ACCESS_TOKEN" \
https://api.localiqservices.com/leads/lsa_events/campaign_rollup?start_date=2020-09-27&end_date=2020-09-28&global_master_advertiser_id=TEST_123' \
Example Response
{
"global_master_advertiser_id": "TEST_123",
"start_date": "2020-09-01",
"end_date": "2020-09-31",
"campaigns": [
{
"global_master_campaign_id": "TEST_1230",
"campaign_name": "GCI | LSA | Bedrock HVAC",
"campaign_type": "lsa",
"lead_counts": [
{
"lead_type": "MESSAGE",
"charged_lead_count": 0,
"not_charged_lead_count": 4,
"total_lead_count": 4,
"total_lead_price": 0.0
},
{
"lead_type": "PHONE_CALL",
"charged_lead_count": 91,
"not_charged_lead_count": 8,
"total_lead_count": 99,
"total_lead_price": 2275.0
}
]
},
{
"global_master_campaign_id": "TEST_1231",
"campaign_name": "GCI | LSA | Bedrock Plumbing",
"campaign_type": "lsa",
"lead_counts": [
{
"lead_type": "MESSAGE",
"charged_lead_count": 0,
"not_charged_lead_count": 3,
"total_lead_count": 3,
"total_lead_price": 0.0
},
{
"lead_type": "PHONE_CALL",
"charged_lead_count": 159,
"not_charged_lead_count": 7,
"total_lead_count": 166,
"total_lead_price": 3975.0
}
]
},
{
"global_master_campaign_id": "TEST_1233",
"campaign_name": "GCI | LSA | Bedrock Electrical",
"campaign_type": "lsa",
"lead_counts": [
{
"lead_type": "MESSAGE",
"charged_lead_count": 0,
"not_charged_lead_count": 3,
"total_lead_count": 3,
"total_lead_price": 0.0
},
{
"lead_type": "PHONE_CALL",
"charged_lead_count": 72,
"not_charged_lead_count": 4,
"total_lead_count": 76,
"total_lead_price": 1080.0
}
]
}
]
}
| Field Name | Datatype | Description |
|---|---|---|
| global_master_advertiser_id | String | Global Master Advertiser ID |
| start_date | String | Start date of report |
| end_date | String | End date of report |
| campaigns | Object | Campaign details. Campaign Detail Object |
| Field Name | Datatype | Description |
|---|---|---|
| global_master_campaign_id | String | ID Of campaign |
| campaign_name | String | The name of the campaign |
| campaign_type | String | The type of campaign |
| lead_counts | Object | Metrics for each lead type. Lead Type Detail Object |
| Field Name | Datatype | Description |
|---|---|---|
| lead_type | String | The type of lead |
| charged_lead_count | Integer | The number of leads of this type for this campaign that were charged |
| not_charged_lead_count | Integer | The number of leads of this type for this campaign that were not charged |
| total_lead_count | Integer | The total number of leads of this type for this campaign |
| total_lead_price | Integer | The price for the charged leads |
LSA Lead Details
Resource Overview
| Method | URI Format |
|---|---|
| GET | /leads/lsa_events?[query_params] |
Use GET to retrieve Local Service Ads Leads for a given advertiser.
The data returned will include individual leads in reverse chronological order.
Parameters
When using the GET method, the results can be filtered using these parameters:
| Param | Required | Function |
|---|---|---|
| global_master_advertiser_id | Yes | Only leads for the specified advertiser will be returned. |
| start_date | Yes | Restricts the results to those ocurring on or after this date. |
| end_date | Yes | Restricts the results to those ocurring on or before this date. |
| global_master_campaign_id[] | No | Restricts the results to those belonging to these campaigns. |
| per_page | No | Restrict number of leads in result. Default is 50 |
| page | No | Specifies which page of results to return. Default is 1 |
To specify a date range:
- Specify start_date and end_date.
Response Data Details
Retrieve data for advertiser and date range
curl -H "Authorization: Bearer OAUTH_ACCESS_TOKEN" \
https://api.localiqservices.com/leads/lsa_events?start_date=2020-09-27&end_date=2020-09-28&global_master_advertiser_id=TEST_123' \
Example Response
{
"global_master_advertiser_id": "TEST_123",
"start_date": "2020-09-27",
"end_date": "2020-09-28",
"page": 1,
"per_page": 50,
"total_pages": 1,
"lsa_events": [
{
"event_id": "4819",
"event_time": "2020-09-27T20:26:30.000Z",
"global_master_campaign_id": "TEST_1232",
"cycle_id": "444",
"lead_type": "PHONE_CALL",
"lead_name": "Mr. Letty Mann",
"lead_phone_number": "126.235.0549 x2631",
"job_type": "install",
"zip_code": "93247-8802",
"lead_category": "hvac",
"charged": "0",
"lead_price": "30",
"campaign_name": "Amazing discount188618s"
},
{
"event_id": "1351",
"event_time": "2020-09-27T19:03:37.000Z",
"global_master_campaign_id": "TEST_1230",
"cycle_id": "444",
"lead_type": "PHONE_CALL",
"lead_name": "Ms. Annita Anderson",
"lead_phone_number": "1-904-299-5528 x85872",
"job_type": "install",
"zip_code": "55939",
"lead_category": "hvac",
"charged": "0",
"lead_price": "30",
"campaign_name": "Sweet savings324049s"
}
]
}
Retrieve data for advertiser and date range, with campaign filter
curl -H "Authorization: Bearer OAUTH_ACCESS_TOKEN" \
https://api.localiqservices.com/leads/lsa_events?start_date=2020-09-27&end_date=2020-09-28&global_master_advertiser_id=TEST_123&global_master_campaign_id[]=TEST_1232' \
Example Response
{
"global_master_advertiser_id": "TEST_123",
"start_date": "2020-09-27",
"end_date": "2020-09-28",
"page": 1,
"per_page": 50,
"total_pages": 1,
"lsa_events": [
{
"event_id": "4819",
"event_time": "2020-09-27T20:26:30.000Z",
"global_master_campaign_id": "TEST_1232",
"cycle_id": "444",
"lead_type": "PHONE_CALL",
"lead_name": "Mr. Letty Mann",
"lead_phone_number": "126.235.0549 x2631",
"job_type": "install",
"zip_code": "93247-8802",
"lead_category": "hvac",
"charged": "0",
"lead_price": "30",
"campaign_name": "Amazing discount188618s"
}
]
}
| Field Name | Datatype | Description |
|---|---|---|
| start_date | String | Start date of report |
| end_date | String | End date of report |
| global_master_advertiser_id | String | Global Master Advertiser ID |
| page | Integer | Page Number of results |
| per_page | Integer | Max number of results per page |
| total_pages | Integer | Number of available pages of results |
| lsa_events | Object | Report details. Lead Detail Object |
| Field Name | Datatype | Description |
|---|---|---|
| event_id | String | ID Of lead |
| event_time | String | Time lead event ocurred |
| global_master_campaign_id | String | ID Of campaign for this lead |
| cycle_id | String | ID of the campaign cycle for this lead |
| lead_type | String | The type of the lead, e.g.: PHONE_CALL |
| lead_name | String | The first and last name of the lead |
| lead_phone_number | String | The leads phone number |
| job_type | String | The type of service job for this lead |
| zip_code | String | The zip code for the lead |
| lead_category | String | The lead category |
| charged | String | Was this a charged lead? |
| lead_price | String | The price of the lead |
| campaign_name | String | The name of the campaign for the lead |
LocaliQ App on Zapier®
Summary: Zapier® is a tool that allows two systems to exchange data without any coding. LocaliQ makes available a lead app on the Zapier® platform for CRM integration.
- The LocaliQ app on Zapier® is available at no additional cost. Please see note below.
- Advertiser IDs (GMAIDs) are maintained through Campaign Central/Corp and can be found in the general settings of your account settings.
Note: There is an additional monthly subscription cost through Zapier®. The cost depends on the number of leads sent per month and the number of leads transmitted between the systems (which Zapier® refers to as "Tasks"). Pricing information for Zapier® can be found here.
LocaliQ App Options:
There are two options under the LocaliQ App on Zapier®.
- Contacts: This trigger supports integration with CRM products. It delivers contact data (first name, last name, email, phone number, etc.) generated for an advertiser in near real-time.
- Contact Interactions: This trigger supports integration with CRM products. It delivers all interactions (or leads) generated for an advertiser in near real-time. View Data Details.
Recommended Usage Pattern:
This is a self-service solution and it is recommended for the client to use their Zapier® account and to create a Zap between our LocaliQ leads app and their CRM app. Leads from all their campaigns will flow real time from our platform to their CRM.
As an alternative, if you would like LocaliQ to create the Zap, maintain, and manage it using our Zapier® account, please reach your account team and request Offer 2095. This service is available at an additional fee.
LocaliQ Account on Zapier
How Do I Connect to My LocaliQ Account on Zapier?
1) Log in to your Zapier account or create a new account.
2) Navigate to "My Apps" from the top menu bar.
3) Now click on "Connect a new account..." and search for "LocaliQ"
4) Use your LocaliQ business user credentials to connect your LocaliQ account to Zapier.
Business User credentials are provided to you by your account team during account creation. These credentials allow you to access the account data through the APIs as well as the Client Center. If you need to check if you have a Business User created or need to reset your password, you can navigate to ReachSecurePay (https://reachsecurepay.com/client/index.php) and enter your email address. If you encounter the error message “Email Address is invalid” or “Email Address not found”, please contact your account management team. If you progress to the login screen, you can select “Create a new password” which will either send you a password reset email or allow you to set your password manually (this will only occur if your password has never been set).
The business user must be set up to allow access to HIPAA information to access HIPAA data through the API. You can reach your account team to check and/or edit privileges on your business user. Please follow the needed due diligence when adding HIPAA privileges to your business user account since the implications of it are far beyond API access to data. This control applies to APIs that provide data that are classified as HIPAA and protected by law.
5) Once that's done you can start creating an automation! Use a pre-made Zap or create your own with the Zap Editor. Creating a Zap requires no coding knowledge and you'll be walked step-by-step through the setup.
6) Need inspiration? See everything that's possible with LocaliQ and Zapier.
Creating a Zap?
1) Click "Make a New Zap!" button in the upper right-hand corner of the Zapier® Dashboard
2) Pick the LocaliQ Contacts or Contact Interactions option as your Trigger
3) Choose the Action to map data to the receiving system (this could either be your CRM's app or a POST to an endpoint)
4) Enable the Zap and your are done!
Also see: Learn key concepts in Zapier®
Contact Interactions
Summary: This HIPAA Compliant trigger returns all interactions (or leads) generated by a campaign for an advertiser.
Contact Interaction Details
| Field | Type | Description |
|---|---|---|
| id | Integer | An integer uniquely identifying this contact interaction. |
| contact_id | Integer | An integer uniquely identifying the contact to which this contact interaction belongs. |
| campaign_id | Integer | An integer uniquely identifying the campaign that this contact interaction is attributed to. |
| campaign_name | String | The name of the campaign that this contact interaction is attributed to. |
| archived_at | Datetime | The date and time which this contact interaction was archived. |
| created_at | Datetime | The date and time which this contact interaction was created. |
| important_at | Datetime | The date and time which this contact interaction was marked important. |
| occured_at | Datetime | The date and time which this contact interaction occurred. This will usually be different than the date that the contact interaction was created. |
| read_at | Datetime | The date and time which this contact interaction was marked read. |
| display_name | String | The display name of the contact interaction. |
| event_type | String | The type of the contact interaction . Valid values are chat, call and form. |
| status | String | The status of the associated contact. Valid values are pending_contact, active_contact interaction, client and none. |
| notes | String | Free form text notes entered by end users onto the contact interaction . |
| tags | Array of String | When present represents a collection of tags use for applying ad-hoc categorization and collation of contact interactions. |
| contact | Contact | The contact to which this contact interaction belongs. See the contacts page of this document for details |
Depending on the type of contact interaction (see the event_type attribute), the payload will also include one of the following:
Chat
| Field | Nullable | Description |
|---|---|---|
| summary | String | A freeform text description of the chat. |
| transcript | Array of ChatTranscripts | An ordered array of chat transcript objects. |
ChatTranscript Object
| Field | Type | Description |
|---|---|---|
| id | Integer | A sequential id of the line chat transcript. It uniquely identifies a line of the chat transcript within this contact interaction. |
| timestamp | Datetime | The date and time that the external chat API registered for this line of the chat transcript. |
| from | String | The display name of the member of the chat who sent this message. |
| message | String | The message body of this line of the chat transcript. |
Call
| Field | Type | Description |
|---|---|---|
| occured_at | Datetime | The date and time that the call occurred. |
| duration | Integer | The duration of the call in seconds. |
| recording_url | String | The URL address to an audio recording of the call. |
Form Fill
| Field | Type | Description |
|---|---|---|
| sub_type | String | The subtype of the form. Valid values are FormPost and FormEmail. |
| full_message | String | The full form message |
| subject | String | |
| extra_fields | Array of String |
Contacts
Summary: This HIPAA Compliant trigger returns all contacts (first name, last name, email and/or phone number) generated by a campaign for an advertiser.
Contact Details
| Field | Type | Description |
|---|---|---|
| id | Integer | An integer uniquely identifying this contact. |
| first_name | String | The first name of the contact. |
| last_name | String | The last name of the contact. |
| String | The email address of the contact. | |
| company | String | The company name for this contact. |
| title | String | The title for this contact. |
| phone_home | String | The home phone number for this contact. |
| phone_work | String | The work phone number for this contact. |
| phone_mobile | String | The mobile phone number for this contact. |
| phone_fax | String | The fax phone number for this contact. |
| address1 | String | The first address line for this contact. |
| address2 | String | The second address line for this contact. |
| city | String | The city for this contact. |
| state | String | The state for this contact. |
| postal | String | The postal code for this contact. |
| country | String | The country for this contact. |
| notes | String | Free form text notes entered by end users for the contact. |
| tags | Array | yes |
| status | String | The status of the contact. Valid values are pending_contact, active_lead, client and none. |
| created_at | Datetime | The date and time which this contact was created. |
| archived_at | Datetime | The date and time which this contact was archived. |
First Party Data API/Apps
The following APIs and Apps make it easy for you to send us First Party Data and for us to infuse that data into your marketing campaigns to achieve better performance harmoniously across campaigns and not be handcuffed by cookies andconstantly changing publisher tracking constraints.
Capture External Events - Confirmed Calls
The Capture External Event - confirmed calls is used to send call information as First Party Data to LocaliQ. Please use this endpoint when you want to inform us of the value of the calls among the ones that were generated by your LocaliQ campaigns. It also accepts minimal PII.
Resource Overview
| Method | URI Format |
|---|---|
| POST | /capture_events/confirmed_calls |
| HTTPS Response Code | Description |
|---|---|
| 200 | Successful |
| 400 | Validation Error |
Capture External Event API is a public LocaliQ external interface for vendors to use. This endpoint is used to inform us of confirmed leads for First Party Data
Parameters
Post Body Parameters
| Parameter | Required | Description |
|---|---|---|
| provider | yes | The provider of the First Party Data. Example: "Acme Co." |
| calls | yes, if leads not supplied | An Array of Call Objects, defined below |
Call Object Parameters
| Data Field | Required | Datatype | Description |
|---|---|---|---|
| gmaid | yes | string | Global Master Advertiser ID - Uppercase platform and underscore between platform and MAID required |
| phone | yes | string | Normalized phone number of the lead |
| duration | yes | number | The duration of the call in seconds |
| recording_url | yes | string | The URL address to an audio recording of the call. |
| occurred_at | no | string | The date and time that the call occurred |
| tag | yes | integer | 1: High Value, 2: Mid Value, 3: Low Value |
Examples
Sample cURL for the Create Calls POST request:
curl -X POST \
https://api.localiqservices.com/capture_events/confirmed_calls \
-H 'Content-Type: application/json' \
-H 'accept: application/json' \
-H 'authorization: Bearer OAUTH_ACCESS_TOKEN' \
-d '{
"provider": "ACME Co.",
"calls":[
{
"occurred_at":"2017-03-10T01:19:23Z",
"gmaid":"USA_172717",
"phone":"8885551212",
"recording_url":"https://myrecording.com/12345",
"duration":"180",
"tag":1
},
{
"occurred_at":"2017-02-10T01:19:23Z",
"gmaid":"USA_172717",
"phone":"+18885551212",
"recording_url":"https://myrecording.com/12346",
"duration":"180",
"tag":1
}
]
}
'
# HTTP Response Status: 200
# Sample cURL for the Create Calls POST request with validation errors:
curl -X POST \
https://api.localiqservices.com/capture_events/confirmed_calls \
-H 'Content-Type: application/json' \
-H 'accept: application/json' \
-H 'authorization: Bearer OAUTH_ACCESS_TOKEN' \
-d '{
"provider": "",
"calls":[
{
"occurred_at":"2017-03-10T01:19:23Z",
"gmaid":"USA_172717",
"phone":"8885551212",
"recording_url":"https://myrecording.com/12345",
"duration":"180",
"tag":1
},
{
"occurred_at":"2017-02-10T01:19:23Z",
"gmaid":"USA_172717",
"phone":"+18885551212",
"recording_url":"https://myrecording.com/12346",
"duration":"180",
"tag":1
}
]
}
'
# HTTP Response Status: 400
# HTTP Response Body:
# [
# "Provider can't be blank"
# ]
# Sample Ruby for the Create Calls POST request:
require "uri"
require "json"
require "net/http"
url = URI("https://api.localiqservices.com/capture_events/confirmed_calls")
http = Net::HTTP.new(url.host, url.port);
request = Net::HTTP::Post.new(url)
request["Accept"] = "application/json"
request["authorization"] = 'Bearer OAUTH_ACCESS_TOKEN'
request["Content-Type"] = "application/json"
request.body = JSON.dump({
"provider": "ACME Co.",
"calls": [
{
"occurred_at": "2017-03-10T01:19:23Z",
"gmaid": "USA_172717",
"phone": "8885551212",
"recording_url": "https://myrecording.com/12345",
"duration": "180",
"tag": 1
},
{
"occurred_at": "2017-02-10T01:19:23Z",
"gmaid": "USA_172717",
"phone": "+18885551212",
"recording_url": "https://myrecording.com/12346",
"duration": "180",
"tag": 1
}
]
})
response = http.request(request)
puts response.read_body
# HTTP Response Status: 200
/* Sample Java for the Create Calls POST request: */
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n \"provider\":\"ACME Co.\",\n \"calls\": [\n {\n \"occurred_at\":\"2017-03-10T01:19:23Z\",\n \"gmaid\":\"USA_172717\",\n \"phone\":\"8885551212\",\n \"recording_url\":\"https://myrecording.com/12345\", \n \"duration\":\"180\",\n \"tag\":1\n },\n {\n \"occurred_at\":\"2017-02-10T01:19:23Z\",\n \"gmaid\":\"USA_172717\",\n \"phone\":\"+18885551212\",\n \"recording_url\":\"https://myrecording.com/12346\", \n \"duration\":\"180\",\n \"tag\":1\n }\n ]\n}");
Request request = new Request.Builder()
.url("https://api.localiqservices.com/capture_events/confirmed_leads")
.method("POST", body)
.addHeader("Accept", "application/json")
.addHeader("authorization", "Bearer OAUTH_ACCESS_TOKEN")
.addHeader("Content-Type", "application/json")
.build();
Response response = client.newCall(request).execute();
/* HTTP Response Status: 200 */
Capture External Events - Chat
Resource Overview
The Capture External Event - Chat endpoint is used to send chat events to LocaliQ.
| Method | URI Format |
|---|---|
| POST | /capture_events/chats |
| HTTPS Response Code | Description |
|---|---|
| 200 | Successful |
| 400 | Validation Error |
Parameters
Examples
Sample cURL for the Create Chat POST request:
curl -X POST \
https://api.localiqservices.com/capture_events/chats \
-H 'Content-Type: application/json' \
-H 'accept: application/json' \
-H 'authorization: Bearer OAUTH_ACCESS_TOKEN' \
-d '{
"eventTime": "2017-03-10T01:19:23Z",
"accountId": "123456789",
"data":
{
"provider": "SomeCompany",
"visitId": "bd4567f4-9b90-42e6-b282-7767af1ba581",
"chatDuration": 261.58,
"chatSummary": "Do you have any specials going on?",
"chatTextFull": "\u000a[2/13/2017 10:55:24 AM] elaine: Hello, thanks for contacting St. Louis Car Dealership. My name is elaine, may I have your name?\u000a [3/9/2017 8:17:50 PM] System: All users have left the chat.",
"chatVisitorEmail": "minneapple@gmail.com",
"chatVisitorName": "Bob",
"chatVisitorPhone": "6592009999"
}
}
'
# HTTP Response Status: 200
# Sample cURL for the Create Chat POST request with validation errors:
curl -X POST \
https://api.localiqservices.com/capture_events/chats \
-H 'Content-Type: application/json' \
-H 'accept: application/json' \
-H 'authorization: Bearer OAUTH_ACCESS_TOKEN' \
-d '{
"eventTime": "2017-03-10T01:19:23Z",
"accountId": "123456789",
"data":
{
"provider": null,
"visitId": "bd4567f4-9b90-42e6-b282-7767af1ba581",
"chatDuration": 261.58,
"chatSummary": "Do you have any specials going on?",
"chatTextFull": "\u000a[2/13/2017 10:55:24 AM] elaine: Hello, thanks for contacting St. Louis Car Dealership. My name is elaine, may I have your name?\u000a [3/9/2017 8:17:50 PM] System: All users have left the chat.",
"chatVisitorEmail": "minneapple@gmail.com",
"chatVisitorName": "Bob",
"chatVisitorPhone": "6592009999"
}
}
'
# HTTP Response Status: 400
# HTTP Response Body:
# [
# "Provider can't be blank"
# ]
# Sample Ruby for the Create Chat POST request:
require 'uri'
require 'net/http'
url = URI("https://api.localiqservices.com/capture_events/chats")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request["accept"] = 'application/json'
request["authorization"] = 'Bearer OAUTH_ACCESS_TOKEN'
request["Content-Type"] = 'application/json'
request.body = "{\n \"eventTime\": \"2017-03-10T01:19:23Z\",\n \"accountId\": \"123456789\",\n \"data\": \n {\n \"provider\": \"SomeCompany\",\n \"visitId\": \"bd4567f4-9b90-42e6-b282-7767af1ba581\", \n \"chatDuration\": 261.58,\n \"chatSummary\": \"Do you have any specials going on?\",\n \"chatTextFull\": \"\u000a[2/13/2017 10:55:24 AM] elaine: Hello, thanks for contacting St. Louis Car Dealership. My name is elaine, may I have your name?\u000a [3/9/2017 8:17:50 PM] System: All users have left the chat.\",\n \"chatVisitorEmail\": \"minneapple@gmail.com\",\n \"chatVisitorName\": \"Bob\",\n \"chatVisitorPhone\": \"6592009999\"\n }\n \n}\n"
response = http.request(request)
puts response.read_body
# HTTP Response Status: 200
/* Sample Java for the Create Chat POST request: */
OkHttpClient client = new OkHttpClient();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n \"eventTime\": \"2017-03-10T01:19:23Z\",\n \"accountId\": \"1213456789\",\n \"data\": \n {\n \"provider\": \"SomeCompany\",\n \"visitId\": \"bd4567f4-9b90-42e6-b282-7767af1ba581\", \n \"chatDuration\": 261.58,\n \"chatSummary\": \"Do you have any specials going on?\",\n \"chatTextFull\": \"\u000a[2/13/2017 10:55:24 AM] elaine: Hello, thanks for contacting St. Louis Car Dealership. My name is elaine, may I have your name?\u000a [3/9/2017 8:17:50 PM] System: All users have left the chat.\",\n \"chatVisitorEmail\": \"minneapple@gmail.com\",\n \"chatVisitorName\": \"Bob\",\n \"chatVisitorPhone\": \"6592009999\"\n }\n \n}\n");
Request request = new Request.Builder()
.url("https://api.localiqservices.com/capture_events/chats")
.post(body)
.addHeader("accept", "application/json")
.addHeader("authorization", "Bearer OAUTH_ACCESS_TOKEN")
.addHeader("Content-Type", "application/json")
.build();
Response response = client.newCall(request).execute();
/* HTTP Response Status: 200 */
Post Body Parameters
| Parameter | Required | Description |
|---|---|---|
| eventTime | yes | The date/time in UTC that the chat started |
| accountId | yes | A vendor supplied account identifier |
| data | yes | A JSON hash representing the attributes for the chat. See the following section for details |
This section defines the data parameter JSON hash:
| Data Field | Required | Description |
|---|---|---|
| provider | yes | The name of the service provider |
| visitId | yes | The LocaliQ visitId of the chat user |
| chatDuration | yes | The duration of the chat in seconds |
| chatSummary | yes | A summary of the chat |
| chatTextFull | yes | The full transcript of the chat |
| chatVisitorEmail | yes | The email address of the visitor |
| chatVisitorName | yes | The name of the chat visitor |
| chatVisitorPhone | no | The phone number for this chat visitor |
| HTTPS Response Code | Description |
|---|---|
| 200 | Successful |
| 400 | Validation Error |
Deprecated APIs
Creative/Ad Metrics
Resource Overview
| Method | URI Format |
|---|---|
| GET | /client_reports/display_creative/[gmaid]?[query_params] |
Note: We recommend users to migrate to the Unified Display API in place of this API as this API will no longer be updated.
Usage
Use GET to retrieve information for the Display Creative Report for a given advertiser.
The data returned will include spend, impressions, clicks, click-through rate (ctr), cost per thousand (cpm), cost per click (cpc), walk-ins, click-through form submissions, view-through form submissions, cost per submission, click-through priority page views, and view-through priority page views organized by campaign and broken down by creative type and creative size.
Parameters
When using the GET method, the results can be filtered using these parameters:
| Param | Function |
|---|---|
| start_date | Restricts the results to those occurring on or after this date |
| end_date | Restricts the results to those occurring on or before this date |
| global_master_campaign_id[] | Restrict results to one or more specific campaigns. This should be a comma separated string. Ex: global_master_campaign_id[]=TEST_1,TEST_2 |
| campaign_status[] | Restrict results to all campaigns with given status values. Allowed values are running, stopped and ended. This should be a comma separated string. Ex: campaign_status[]=running,stopped |
| campaign_types[] | Default: display (can be used to return other campaign types) |
| campaign_cycle | Restrict results to a single campaign cycle |
| interval_size | Use calendar_month or calendar_week to roll up the data points into calendar intervals (default is 1 day per interval) |
To specify a date range:
- Specify start_date and end_date.
- When specifying a
campaign_cycle, do not use date range params.
Response Data Details
Retrieve data for a specific range of dates
curl -H "Authorization: Bearer OAUTH_ACCESS_TOKEN" \
https://api.localiqservices.com/client_reports/display_creative/TEST_1?start_date=2018-05-01&end_date=2018-05-01
Retrieve data for a specific campaign starting on a certain date
curl -H "Authorization: Bearer OAUTH_ACCESS_TOKEN" \
https://api.localiqservices.com/client_reports/display_creative/TEST_1?global_master_campaign_id[]=TEST_1&start_date=2018-05-01&end_date=2018-05-01
Retrieve data for a specific campaign cycle
curl -H "Authorization: Bearer OAUTH_ACCESS_TOKEN" \
https://api.localiqservices.com/client_reports/display_creative/TEST_1?campaign_cycle=TEST_1
Retrieve data for campaigns that are stopped and running
curl -g -H "Authorization: Bearer OAUTH_ACCESS_TOKEN" \
https://api.localiqservices.com/client_reports/display_creative/TEST_1?&campaign_status[]=running,stopped&start_date=2018-05-01&end_date=2018-05-01
Example Response
{
"report_type": "display_creative", // Type Of Report
"report_date": "2018-06-13", // Date Report Ran
"earliest_date_available": "2017-12-04", // How Far Back Data is Available
"start_date": "2018-05-01", // Start Date of Report
"end_date": "2018-05-01", // End Date of Report
"time_zone": "America/Los_Angeles", // Time Zone
"interval_size": "day", // Interval Size ('day', 'calendar_week' or 'calendar_month')
"global_master_advertiser_id": "TEST_1", // Global Master Advertiser (GMAID) for report
"report_data": { // Report Details
"campaigns": [ // All Data for Campaigns
{
"name": "GeoFence | FCS | Lee County Oncology Competitors", // Campaign Name
"global_master_campaign_id": "TEST_1", // Identifier for Campaign
"start_date": "2018-05-01", // Start Date for Campaign
"end_date": null, // End Date for Campaign
"type": "display", // Type of Campaign
"status": "running", // Campaign Status
"intervals": [ // Data for Specified Interval
{
"start_date": "2018-05-01", // Start Date of Interval
"spend": 16.68, // Spend for Interval
"impressions": 3029, // Impressions for Interval
"clicks": 4, // Clicks for Interval
"ctr": 0.13, // Spend for Interval
"cpm": 5.51, // Cost per Thousand for Interval
"cpc": 4.17, // Cost per Click for Interval
"walk_ins": 21, // Walk-ins for Interval
"form_submissions_ct": 0, // Click-Through Form Submissions
"form_submissions_vt": 0, // View-Through Form Submissions
"cost_per_submission": 0, // Cost per Form Submission
"priority_page_views_ct": 0, // Click-Through Priority Page Views
"priority_page_views_vt": 0, // View-Through Priority Page Views
"creative_types": [ // Creative Types for Interval
{
"creative_type": "Rich Media", // Creative Type
"spend": 16.68, // Spend for Creative Type
"impressions": 3029, // Impressions for Creative Type
"clicks": 4, // Clicks for Creative Type
"ctr": 0.13, // Click-Through Rate for Creative Type
"cpm": 5.51, // Cost per Thousand for Creative Type
"cpc": 4.17, // Cost per Click for Creative Type
"walk_ins": 21, // Walk-ins for Creative Type
"form_submissions_ct": 0, // Click-Through Form Submissions
"form_submissions_vt": 0, // View-Through Form Submissions
"cost_per_submission": 0, // Cost per Form Submission
"priority_page_views_ct": 0, // Click-Through Priority Page Views
"priority_page_views_vt": 0, // View-Through Priority Page Views
"creative_sizes": [ // Creative Sizes for Creative Type
{
"creative_size": "160x600", // Creative Size
"spend": 0.3, // Spend for Creative Size
"impressions": 48, // Impressions for Creative Size
"clicks": 0, // Clicks for Creative Size
"ctr": 0, // Click-Through Rate for Creative Size
"cpm": 6.33, // Cost per Thousand for Creative Size
"cpc": 0, // Cost per Click for Creative Size
"walk_ins": 0, // Walk-ins for Creative Size
"form_submissions_ct": 0, // Click-Through Form Submissions
"form_submissions_vt": 0, // View-Through Form Submissions
"cost_per_submission": 0, // Cost per Submission
"priority_page_views_ct": 0, // Click-Through Priority Page Views
"priority_page_views_vt": 0 // View-Through Priority Page Views
},
{
"creative_size": "250x250",
"spend": 0.1,
"impressions": 19,
"clicks": 0,
"ctr": 0,
"cpm": 5,
"cpc": 0,
"walk_ins": 0,
"form_submissions_ct": 0,
"form_submissions_vt": 0,
"cost_per_submission": 0,
"priority_page_views_ct": 0,
"priority_page_views_vt": 0
},
{
"creative_size": "300x50",
"spend": 0.58,
"impressions": 106,
"clicks": 1,
"ctr": 0.94,
"cpm": 5.5,
"cpc": 0.58,
"walk_ins": 3,
"form_submissions_ct": 0,
"form_submissions_vt": 0,
"cost_per_submission": 0,
"priority_page_views_ct": 0,
"priority_page_views_vt": 0
},
{
"creative_size": "300x250",
"spend": 5.55,
"impressions": 1026,
"clicks": 1,
"ctr": 0.1,
"cpm": 5.41,
"cpc": 5.55,
"walk_ins": 3,
"form_submissions_ct": 0,
"form_submissions_vt": 0,
"cost_per_submission": 0,
"priority_page_views_ct": 0,
"priority_page_views_vt": 0
},
{
"creative_size": "320x50",
"spend": 8.73,
"impressions": 1571,
"clicks": 1,
"ctr": 0.06,
"cpm": 5.55,
"cpc": 8.73,
"walk_ins": 15,
"form_submissions_ct": 0,
"form_submissions_vt": 0,
"cost_per_submission": 0,
"priority_page_views_ct": 0,
"priority_page_views_vt": 0
},
{
"creative_size": "320x480",
"spend": 0.05,
"impressions": 8,
"clicks": 0,
"ctr": 0,
"cpm": 5.89,
"cpc": 0,
"walk_ins": 0,
"form_submissions_ct": 0,
"form_submissions_vt": 0,
"cost_per_submission": 0,
"priority_page_views_ct": 0,
"priority_page_views_vt": 0
},
{
"creative_size": "728x90",
"spend": 1.37,
"impressions": 251,
"clicks": 1,
"ctr": 0.4,
"cpm": 5.46,
"cpc": 1.37,
"walk_ins": 0,
"form_submissions_ct": 0,
"form_submissions_vt": 0,
"cost_per_submission": 0,
"priority_page_views_ct": 0,
"priority_page_views_vt": 0
}
]
}
]
}
]
}
],
"totals_per_interval": [ // Totals per Interval (over multiple campaigns)
{
"start_date": "2018-05-01", // Start Date of Interval
"spend": 16.68, // Total Spend for Interval
"impressions": 3029, // Total Impressions for interval
"clicks": 4, // Total Clicks for Interval
"ctr": 0.13, // Total Click-Through rate for Interval
"cpm": 5.51, // Total Cost per Thousand for Interval
"cpc": 4.17, // Total Cost per Click for Interval
"walk_ins": 21, // Total Walk-ins for Interval
"form_submissions_ct": 0, // Total Click-Through Form Submissions
"form_submissions_vt": 0, // Total View-Through Form Submissions
"cost_per_submission": 0, // Total Cost per Submission
"priority_page_views_ct": 0, // Total Click-Through Priority Page Views
"priority_page_views_vt": 0 // Total View-Through Priority Page Views
}
],
"totals": { // Total Data
"spend": 16.68, // Total Spend
"impressions": 3029, // Total Impressions
"clicks": 4, // Total Clicks
"ctr": 0.13, // Total Click-Through Rate
"cpm": 5.51, // Total Cost per Thousand
"cpc": 4.17, // Total Cost per Click
"walk_ins": 21, // Total Walk-ins
"form_submissions_ct": 0, // Total Click-Through Form Submissions
"form_submissions_vt": 0, // Total View-Through Form Submissions
"cost_per_submission": 0, // Total Cost per Submission
"priority_page_views_ct": 0, // Total Click-Through Priority Page Views
"priority_page_views_vt": 0 // Total View-Through Priority Page Views
}
}
}
Display Campaign Metrics Old
Resource Overview
| Method | URI Format |
|---|---|
| GET | /client_reports/display_activity/[gmaid]?[query_params] |
Note: We recommend users to migrate to the Unified Display API in place of this API as this API will no longer be updated.
Usage
Use GET to retrieve information for the Display Activity report for a given advertiser.
The data returned will include impressions, remarketing impressions, custom targeting impressions, clicks, spend, CPM, walk-ins, and CPW values organized by campaign and campaign_cycle.
Parameters
When using the GET method, the results can be filtered using these parameters:
| Param | Function |
|---|---|
| start_date | Restricts the results to those occurring on or after this date |
| end_date | Restricts the results to those occurring on or before this date |
| global_master_campaign_id[] | Restrict results to one or more specific campaigns. This should be a comma separated string. Ex: global_master_campaign_id[]=TEST_1,TEST_2 |
| campaign_status[] | Restrict results to all campaigns with given status values. Allowed values are running, stopped and ended. This should be a comma separated string. Ex: campaign_status[]=running,stopped |
| campaign_cycle | Restrict results to a single campaign cycle |
| interval_size | Use calendar_month or calendar_week to roll up the data points into calendar intervals (default is 1 day per interval) |
| campaign_types[] | Default: display (can be used to return other campaign types) |
| include_cycles | Set to true or false on whether to include cycle nesting. Default value is false |
To specify a date range:
- Specify start_date and end_date.
- When specifying a campaign_cycle, do not use date range params.
Response Data Details
Retrieve data for a specific range of dates
curl -H "Authorization: Bearer OAUTH_ACCESS_TOKEN" \
https://api.localiqservices.com/client_reports/display_activity/TEST_1?start_date=2016-12-01&end_date=2016-12-31
Retrieve data for a specific campaign starting on a certain date
curl -H "Authorization: Bearer OAUTH_ACCESS_TOKEN" \
https://api.localiqservices.com/client_reports/display_activity/TEST_1?global_master_campaign_id[]=TEST_1&start_date=2016-10-01&end_date=2016-12-31
Retrieve data for a specific campaign cycle
curl -H "Authorization: Bearer OAUTH_ACCESS_TOKEN" \
https://api.localiqservices.com/client_reports/display_activity/TEST_1?campaign_cycle=TEST_1
Retrieve data for campaigns that are stopped and running
curl -g -H "Authorization: Bearer OAUTH_ACCESS_TOKEN" \
https://api.localiqservices.com/client_reports/display_activity/TEST_1?&campaign_status[]=running,stopped&start_date=2016-10-01&end_date=2016-12-31
Retrieve data for a specific campaign starting on a certain date with cycle nesting
curl -g -H "Authorization: Bearer OAUTH_ACCESS_TOKEN \
https://api.localiqservices.com/client_reports/search_activity/TEST_1?global_master_campaign_id[]=TEST_1&start_date=2016-10-01&end_date=2016-12-31&include_cycles=true
Response Description with Cycles
{
"report_type": "display_activity", // Type of report
"report_date": "2016-10-24", // Date report ran
"earliest_date_available": "2016-01-01", // How far back data is available
"start_date": "2016-10-10", // Start date of report
"end_date": "2016-10-24", // End date of report
"time_zone": "America/Los_Angeles", // Time Zone
"interval_size": "day", // Interval Size ('day', 'calendar_week' or 'calendar_month')
"currency": "USD", // Currency
"report_data": { // Report details
"campaigns": [ // All data for campaigns
{
"name": "Ad_Campaign_1", // Campaign name
"global_master_campaign_id": "TEST_1",// Identifier for campaign
"start_date": "2016-07-10", // Start date for campaign
"end_date": "2016-10-24", // End date for campaign
"type": "display", // Type of campaign
"cycles": [ // Data for cycles
{
"campaign_cycle": "TEST_1", // Identifier for cycle
"start_date": "2016-10-10", // Start date for cycle
"end_date": "2016-10-14", // End date for cycle
"intervals": [ // Data for specified interval
{
"start_date": "2016-10-10", // Start date of interval
"impressions": 78, // Impressions for interval
"remarketing_impressions": 59, // Remarketing impressions for interval
"custom_targeting_impressions": 65, // Custom targeting impressions for interval
"clicks": 45, // Clicks for interval
"spend": 18, // Spend for interval
"cpm": 3.05, // CPM for interval
"ctr": 57.69, // Click through rate
"performance_impressions": 21268, // Performance (video) impressions
"calls": 0, // Calls for interval
"video_views": 0, // Video Views (started) for interval
"completed_views": 0, // Video Views (completed) for interval
"form_submissions_ct": 2, // Click-Through Form Submissions
"form_submissions_vt": 5, // View-Through Form Submissions
"priority_page_views_ct": 0, // Click-Through Priority Page Views
"priority_page_views_vt": 0, // View-Through Priority Page Views
"view_complete_rate": 0, // Percent of videos completed
"view_through_rate": 0, // View Through Rate (percent)
"walk_ins": 1, // Walk-ins
"cpw": 18.0 // Cost per Walk-in
"cost_per_call": 0, // Cost per Call
"cost_per_submission": 17.87 // Cost per Form Submission
},
]
}
]
}
],
"totals": { // Total data
"impressions": 78, // Total impressions
"remarketing_impressions": 310, // Total remarketing_impressions
"custom_targeting_impressions": 45, // Total custom_targeting_impressions
"clicks": 85, // Total click events
"spend": 18, // Total spend
"cpm": 4.05, // Total CPM
"ctr": 57.69, // Click through rate
"walk_ins": 1, // Total Walk-ins
"performance_impressions": 64213, // Total Performance Impressions
"calls": 0, // Total Calls
"video_views": 0, // Total Video View
"completed_views": 0, // Total Completed Video Views
"form_submissions_ct": 3, // Total Click-Through Form Submissions
"form_submissions_vt": 5, // Total View-Through Form Submissions
"priority_page_views_ct": 0, // Total Click-Through Priority Page Views
"priority_page_views_vt": 0, // Total View-Through Priority Page Views
"view_through_rate": 0, // Total View-Through Rate (percent)
"video_complete_rate": 0, // Total Video Completion Rate (percent)
"cpw": 18.0 // Total Cost per Walk-in
"cost_per_call": 0, // Total Cost per Call
"cost_per_submission": 78.21 // Total Cost per Form Submission
},
"totals_per_interval": [ // Totals per interval (over multiple campaigns)
{
"start_date": "2016-10-10", // Start date of interval
"impressions": 78, // Total impressions for interval
"remarketing_impressions": 310, // Total remarketing impressions for interval
"custom_targeting_impressions": 45, // Total custom targeting impressions for interval
"clicks": 85, // Total clicks for interval
"spend": 18, // Total spend for interval
"cpm": 4.05, // Total cpm for interval
"ctr": 57.69, // Click through rate
"performance_impressions": 21268, // Performance (video) impressions
"calls": 0, // Total Calls for interval
"video_views": 0, // Total Video Views (started) for interval
"completed_views": 0, // Total Video Views (completed) for interval
"form_submissions_ct": 2, // Total Click-Through Form Submissions for interval
"form_submissions_vt": 5, // Total View-Through Form Submissions for interval
"priority_page_views_ct": 0, // Total Click-Through Priority Page Views for interval
"priority_page_views_vt": 0, // Total View-Through Priority Page Views for interval
"view_complete_rate": 0, // Total Percent of videos completed for interval
"view_through_rate": 0, // Total View Through Rate (percent) for interval
"walk_ins": 1, // Total Walk-ins for interval
"cpw": 52.37 // Total Cost per Walk-ins for interval
"cost_per_call": 0, // Total Cost per Call for interval
"cost_per_submission": 17.87 // Total Cost per Form Submission for interval
}
]
},
"global_master_advertiser_id": "TEST_1" // Identifier for advertiser
}
Response Description without Cycles
{
"report_type": "display_activity", // Type of report
"report_date": "2016-10-24", // Date report ran
"earliest_date_available": "2016-01-01", // How far back data is available
"start_date": "2016-10-10", // Start date of report
"end_date": "2016-10-24", // End date of report
"time_zone": "America/Los_Angeles", // Time Zone
"interval_size": "day", // Interval Size ('day', 'calendar_week' or 'calendar_month')
"currency": "USD", // Currency
"report_data": { // Report details
"campaigns": [ // All data for campaigns
{
"name": "Ad_Campaign_1", // Campaign name
"global_master_campaign_id": "TEST_1",// Identifier for campaign
"start_date": "2016-07-10", // Start date for campaign
"end_date": "2016-10-24", // End date for campaign
"type": "display", // Type of campaign
"intervals": [ // Data for specified interval
{
"start_date": "2016-10-10", // Start date of interval
"impressions": 78, // Impressions for interval
"remarketing_impressions": 59, // Remarketing impressions for interval
"custom_targeting_impressions": 65, // Custom targeting impressions for interval
"clicks": 45, // Clicks for interval
"spend": 18, // Spend for interval
"cpm": 3.05, // CPM for interval
"ctr" : 57.69, // Click through rate
"performance_impressions": 21268, // Performance (video) impressions
"calls": 0, // Calls for interval
"video_views": 0, // Video Views (started) for interval
"completed_views": 0, // Video Views (completed) for interval
"form_submissions_ct": 2, // Click-Through Form Submissions
"form_submissions_vt": 5, // View-Through Form Submissions
"priority_page_views_ct": 0, // Click-Through Priority Page Views
"priority_page_views_vt": 0, // View-Through Priority Page Views
"view_complete_rate": 0, // Percent of videos completed
"view_through_rate": 0, // View Through Rate (percent)
"walk_ins": 1, // Walk-ins
"cpw": 18.0 // Cost per Walk-in
"cost_per_call": 0, // Cost per Call
"cost_per_submission": 17.87 // Cost per Form Submission
},
]
}
],
"totals": { // Total data
"impressions": 78, // Total impressions
"remarketing_impressions": 310, // Total remarketing_impressions
"custom_targeting_impressions": 45, // Total custom_targeting_impressions
"clicks": 85, // Total click events
"spend": 18, // Total spend
"cpm": 4.05, // Total CPM
"ctr": 57.69, // Click through rate
"walk_ins": 1, // Total Walk-ins
"performance_impressions": 64213, // Total Peformance Impressions
"calls": 0, // Total Calls
"video_views": 0, // Total Video View
"completed_views": 0, // Total Completed Video Views
"form_submissions_ct": 3, // Total Click-Through Form Submissions
"form_submissions_vt": 5, // Total View-Through Form Submissions
"priority_page_views_ct": 0, // Total Click-Through Priority Page Views
"priority_page_views_vt": 0, // Total View-Through Priority Page Views
"view_through_rate": 0, // Total View-Through Rate (percent)
"video_complete_rate": 0, // Total Video Completion Rate (percent)
"cpw": 18.0 // Total Cost per Walk-in
"cost_per_call": 0, // Total Cost per Call
"cost_per_submission": 78.21 // Total Cost per Form Submission
},
"totals_per_interval": [ // Totals per interval (over multiple campaigns)
{
"start_date": "2016-10-10", // Start date of interval
"impressions": 78, // Total impressions for interval
"remarketing_impressions": 310, // Total remarketing impressions for interval
"custom_targeting_impressions": 45, // Total custom targeting impressions for interval
"clicks": 85, // Total clicks for interval
"spend": 18, // Total spend for interval
"cpm": 4.05, // Total cpm for interval
"ctr": 57.69, // Click through rate
"performance_impressions": 21268, // Performance (video) impressions
"calls": 0, // Total Calls for interval
"video_views": 0, // Total Video Views (started) for interval
"completed_views": 0, // Total Video Views (completed) for interval
"form_submissions_ct": 2, // Total Click-Through Form Submissions for interval
"form_submissions_vt": 5, // Total View-Through Form Submissions for interval
"priority_page_views_ct": 0, // Total Click-Through Priority Page Views for interval
"priority_page_views_vt": 0, // Total View-Through Priority Page Views for interval
"view_complete_rate": 0, // Total Percent of videos completed for interval
"view_through_rate": 0, // Total View Through Rate (percent) for interval
"walk_ins": 0, // Total Walk-ins for interval for interval
"cpw": 0, // Total Cost per Walk-in for interval
"cost_per_call": 0, // Total Cost per Call for interval
"cost_per_submission": 17.87 // Total Cost per Form Submission for interval
}
]
},
"global_master_advertiser_id": "TEST_1" // Identifier for advertiser
}
Example Response (without cycles):
{
"report_type": "display_activity",
"report_date": "2017-01-24",
"earliest_date_available": "2016-01-01",
"start_date": "2017-01-11",
"end_date": "2017-01-13",
"time_zone": "America/Los_Angeles",
"interval_size": "day",
"currency": "USD",
"report_data": {
"campaigns": [
{
"name": "Drain Cleaning",
"global_master_campaign_id": "TEST_1",
"start_date": "2016-11-14",
"end_date": "2017-01-13",
"type": "display",
"status": "running",
"intervals": [
{
"start_date": "2017-01-11",
"impressions": 200,
"remarketing_impressions": 60,
"custom_targeting_impressions": 140,
"clicks": 30,
"spend": 75.5,
"cpm": 377.5,
"ctr": 57.69,
"performance_impressions": 21268,
"calls": 0,
"video_views": 0,
"completed_views": 0,
"form_submissions_ct": 2,
"form_submissions_vt": 5,
"priority_page_views_ct": 0,
"priority_page_views_vt": 0,
"view_complete_rate": 0,
"view_through_rate": 0,
"walk_ins": 0,
"cpw": 0,
"cost_per_call": 0,
"cost_per_submission": 17.87
},
{
"start_date": "2017-01-12",
"impressions": 200,
"remarketing_impressions": 60,
"custom_targeting_impressions": 140,
"clicks": 30,
"spend": 75.5,
"cpm": 377.5,
"ctr": 57.69,
"performance_impressions": 21268,
"calls": 0,
"video_views": 0,
"completed_views": 0,
"form_submissions_ct": 2,
"form_submissions_vt": 5,
"priority_page_views_ct": 0,
"priority_page_views_vt": 0,
"view_complete_rate": 0,
"view_through_rate": 0,
"walk_ins": 0,
"cpw": 0,
"cost_per_call": 0,
"cost_per_submission": 17.87
},
{
"start_date": "2017-01-13",
"impressions": 200,
"remarketing_impressions": 60,
"custom_targeting_impressions": 140,
"clicks": 30,
"spend": 75.5,
"cpm": 377.5,
"ctr": 57.69,
"performance_impressions": 21268,
"calls": 0,
"video_views": 0,
"completed_views": 0,
"form_submissions_ct": 2,
"form_submissions_vt": 5,
"priority_page_views_ct": 0,
"priority_page_views_vt": 0,
"view_complete_rate": 0,
"view_through_rate": 0,
"walk_ins": 0,
"cpw": 0,
"cost_per_call": 0,
"cost_per_submission": 17.87
}
]
},
{
"name": "Stopped Campaign",
"global_master_campaign_id": "TEST_1",
"start_date": "2016-11-14",
"end_date": "2017-01-13",
"type": "display",
"status": "stopped",
"intervals": [
{
"start_date": "2017-01-11",
"impressions": 200,
"remarketing_impressions": 60,
"custom_targeting_impressions": 140,
"clicks": 30,
"spend": 75.5,
"cpm": 377.5,
"ctr": 57.69,
"performance_impressions": 21268,
"calls": 0,
"video_views": 0,
"completed_views": 0,
"form_submissions_ct": 2,
"form_submissions_vt": 5,
"priority_page_views_ct": 0,
"priority_page_views_vt": 0,
"view_complete_rate": 0,
"view_through_rate": 0,
"walk_ins": 0,
"cpw": 0,
"cost_per_call": 0,
"cost_per_submission": 17.87
},
{
"start_date": "2017-01-12",
"impressions": 200,
"remarketing_impressions": 60,
"custom_targeting_impressions": 140,
"clicks": 30,
"spend": 75.5,
"cpm": 377.5,
"ctr": 57.69,
"performance_impressions": 21268,
"calls": 0,
"video_views": 0,
"completed_views": 0,
"form_submissions_ct": 2,
"form_submissions_vt": 5,
"priority_page_views_ct": 0,
"priority_page_views_vt": 0,
"view_complete_rate": 0,
"view_through_rate": 0,
"walk_ins": 0,
"cpw": 0,
"cost_per_call": 0,
"cost_per_submission": 17.87
},
{
"start_date": "2017-01-13",
"impressions": 200,
"remarketing_impressions": 60,
"custom_targeting_impressions": 140,
"clicks": 30,
"spend": 75.5,
"cpm": 377.5,
"ctr": 57.69,
"performance_impressions": 21268,
"calls": 0,
"video_views": 0,
"completed_views": 0,
"form_submissions_ct": 2,
"form_submissions_vt": 5,
"priority_page_views_ct": 0,
"priority_page_views_vt": 0,
"view_complete_rate": 0,
"view_through_rate": 0,
"walk_ins": 0,
"cpw": 0,
"cost_per_call": 0,
"cost_per_submission": 17.87
}
]
},
{
"name": "Ended Campaign",
"global_master_campaign_id": "TEST_1",
"start_date": "2016-11-14",
"end_date": "2017-01-13",
"type": "display",
"status": "ended",
"intervals": [
{
"start_date": "2017-01-11",
"impressions": 200,
"remarketing_impressions": 60,
"custom_targeting_impressions": 140,
"clicks": 30,
"spend": 75.5,
"cpm": 377.5,
"ctr": 57.69,
"performance_impressions": 21268,
"calls": 0,
"video_views": 0,
"completed_views": 0,
"form_submissions_ct": 2,
"form_submissions_vt": 5,
"priority_page_views_ct": 0,
"priority_page_views_vt": 0,
"view_complete_rate": 0,
"view_through_rate": 0,
"walk_ins": 0,
"cpw": 0,
"cost_per_call": 0,
"cost_per_submission": 17.87
},
{
"start_date": "2017-01-12",
"impressions": 200,
"remarketing_impressions": 60,
"custom_targeting_impressions": 140,
"clicks": 30,
"spend": 75.5,
"cpm": 377.5,
"ctr": 57.69,
"performance_impressions": 21268,
"calls": 0,
"video_views": 0,
"completed_views": 0,
"form_submissions_ct": 2,
"form_submissions_vt": 5,
"priority_page_views_ct": 0,
"priority_page_views_vt": 0,
"view_complete_rate": 0,
"view_through_rate": 0,
"walk_ins": 0,
"cpw": 0,
"cost_per_call": 0,
"cost_per_submission": 17.87
},
{
"start_date": "2017-01-13",
"impressions": 200,
"remarketing_impressions": 60,
"custom_targeting_impressions": 140,
"clicks": 30,
"spend": 75.5,
"cpm": 377.5,
"ctr": 57.69,
"performance_impressions": 21268,
"calls": 0,
"video_views": 0,
"completed_views": 0,
"form_submissions_ct": 2,
"form_submissions_vt": 5,
"priority_page_views_ct": 0,
"priority_page_views_vt": 0,
"view_complete_rate": 0,
"view_through_rate": 0,
"walk_ins": 0,
"cpw": 0,
"cost_per_call": 0,
"cost_per_submission": 17.87
}
]
}
],
"totals": {
"impressions": 1800,
"remarketing_impressions": 540,
"custom_targeting_impressions": 1260,
"clicks": 270,
"spend": 679.5,
"cpm": 377.5,
"ctr": 57.69
},
"totals_per_interval": [
{
"start_date": "2017-01-11",
"impressions": 600,
"remarketing_impressions": 180,
"custom_targeting_impressions": 420,
"clicks": 90,
"spend": 226.5,
"cpm": 377.5,
"ctr": 57.69,
"performance_impressions": 21268,
"calls": 0,
"video_views": 0,
"completed_views": 0,
"form_submissions_ct": 2,
"form_submissions_vt": 5,
"priority_page_views_ct": 0,
"priority_page_views_vt": 0,
"view_complete_rate": 0,
"view_through_rate": 0,
"walk_ins": 0,
"cpw": 0,
"cost_per_call": 0,
"cost_per_submission": 17.87
},
{
"start_date": "2017-01-12",
"impressions": 600,
"remarketing_impressions": 180,
"custom_targeting_impressions": 420,
"clicks": 90,
"spend": 226.5,
"cpm": 377.5,
"ctr": 57.69,
"performance_impressions": 21268,
"calls": 0,
"video_views": 0,
"completed_views": 0,
"form_submissions_ct": 2,
"form_submissions_vt": 5,
"priority_page_views_ct": 0,
"priority_page_views_vt": 0,
"view_complete_rate": 0,
"view_through_rate": 0,
"walk_ins": 0,
"cpw": 0,
"cost_per_call": 0,
"cost_per_submission": 17.87
},
{
"start_date": "2017-01-13",
"impressions": 600,
"remarketing_impressions": 180,
"custom_targeting_impressions": 420,
"clicks": 90,
"spend": 226.5,
"cpm": 377.5,
"ctr": 57.69,
"performance_impressions": 21268,
"calls": 0,
"video_views": 0,
"completed_views": 0,
"form_submissions_ct": 2,
"form_submissions_vt": 5,
"priority_page_views_ct": 0,
"priority_page_views_vt": 0,
"view_complete_rate": 0,
"view_through_rate": 0,
"walk_ins": 0,
"cpw": 0,
"cost_per_call": 0,
"cost_per_submission": 17.87
}
]
},
"global_master_advertiser_id": "TEST_1"
}
Error Codes
The LocalIQ API uses standard HTTP status codes to communicate errors
| Error Code | Meaning |
|---|---|
| 200 | OK - Everything went as planned. |
| 400 | Bad Request - Something in your header or request body was malformed. |
| 401 | Unauthorized - Necessary credentials were either missing or invalid. |
| 403 | Forbidden - The end user is authenticated, but is not authorized to access the requested resource. The API response will give information on why this is the case. Unauthorized permissions can be due to advertisers not being active or the user calling the API does not have privileges to access HIPAA info. |
| 404 | Not Found - The object you’re requesting doesn’t exist. |
| 422 | Unprocessable Entity - There is a missing or invalid parameter. The API response will state what parameter needs attention. |
| 429 | Too Many Requests - You are calling our APIs more frequently than we allow. |
| 5xx | Server Error - Something went wrong on our end. |
In addition to the status code, the HTTP body of the response will also contain a JSON representation of the error.
Troubleshooting Errors
400 - Bad Request
Invalid Grant
Example Response
{ "error": "invalid_grant", "error_description": "The provided authorization credentials are invalid. Refer to documentation at https://doc.api.localiq.com/#error-codes for further information." }
Invalid grant error messages occurs when either:
A request is made for an access token with invalid credentials (username or password)
When a request is made to refresh an access token with an expired refresh token, one that has already been used to obtain an access token so it is no longer valid.
To resolve this check your username and password for accuracy, then follow steps at Requesting Access and Refresh Tokens to request a new refresh token.
401 - Unauthorized
Example Response
{ "message": "Unauthorized" }
Unauthorized messages can occur when a request for a report endpoint is made using an expired token.
To resolve this, follow steps at Requesting Access and Refresh Tokens
403 - Forbidden
Example Response
{ "name": "not_authorized", "message": "You are not permitted to perform this action." }
HIPAA Permissions
The business user must be set up to allow access to HIPAA information to access HIPAA data through the API. You can reach your account team to check and/or edit privileges on your business user. Please follow the needed due diligence when adding HIPAA privileges to your business user account since the implications of it are far beyond API access to data.
This control applies to APIs that provide data that are classified as HIPAA and protected by law.
The business user must have "Agency Customer" role to use the lead APIs. If the API response has PII and the advertiser falls under the HIPAA category, the API will check for this role in order to provide PII information in the response.