A
Ads data
Ads data is called “spots” in the iSpot REST API. Endpoint: https://api.ispot.tv/v4/spots
API
Application Programming Interface (API). An API allows applications to communicate with one another. Based on client requests, a publicly available web-based API returns data, most likely in either JSON or XML.
Authentication
The iSpot REST API currently only supports authentication via OAuth v2.0. We recommend that customers use different OAuth Clients for each application that calls the API. OAuth (Open Authorization) is an open standard for token-based authentication and authorization on the internet.
Authorization
To gain authorized access to the iSpot REST API, customers are required to use OAuth v2.0.
E
Endpoint
An endpoint is one end of a communication channel. When an API interacts with another system, the touchpoints of this communication are considered endpoints. For APIs, an endpoint can include a URL of a server or service. Each endpoint is the location from which APIs can access the resources they need to carry out their function.
F
Filter
The API is generally already filtered for you to access the appropriate brand or industry. In order to filter further, you can use the prefix filter parameter in brackets with other general filters and TV conversion filters. There are two forms of filtering: by row values and by column values. You can use both forms with preset values or any field returned in a response.
H
HTTP client
Examples of HTTP clients include Python, curl, Postman, and Insomnia that you can use to make requests to the iSpot REST API.
HTTP status codes
REST APIs use the Status-Line part of an HTTP response message to inform clients of their request’s overarching result. HTTP defines 40 standard status codes to convey the client request results. The status codes are divided into the five categories: 1xx: Informational, 2xx: Success, 3xx: Redirection, 4xx: Client Error, and 5xx: Server Error.
Historical data
The API REST API contains all historical data. However, if you require more than 1 year of historical data, please contact us.
I
Include parameter
You can use the Include parameter to obtain a particular piece of data from an iSpot REST API request. If a specific piece of data is not returned by default in your iSpot API request, use the Include parameter to specify the data in the request. Example: include=network,creative
iSpot Analytics Dashboard
The iSpot Analytics Dashboard enables brands, agencies, TV networks and analysts to track a variety of key performance indicators associated with television advertising. Customers can use the Analytics Dashboard to provide real-time insights into which ads are running, on which networks and shows, when spots run, and how much is being spent on them. Users can also track placement patterns, creatives, and spending levels across industry verticals, as well as drill down into very specific data for a single brand or campaign.
ISO 8601
ISO 8601 is an international standard format covering the exchange of date- and time-related data. Example: YYYY-MM-DDThh:mm:ssZ. The Start Date and End Date filters for iSpot REST API requests require this format.
O
OAuth v2.0
Gaining client access to the iSpot REST API requires using OAuth v2.0. iSpot provides customers with client credentials, which they can then use to generate an OAuth v2.0 token that authorizes their access the iSpot REST API. OAuth (Open Authorization) is an open standard for token-based authentication and authorization on the internet. OAuth, which is pronounced "oh-auth," allows user account information to be used by third-party services without exposing the user passwords.
OAuth Client
iSpot account managers use our internal tools to create OAuth Clients for our customers. Through this process, each customer receives a Client ID and a Client Secret in a secure manner that is required in order to access the iSpot REST API.
OAuth v2.0 token
The OAuth 2.0 authorization code flow performs authentication and authorization for web apps and natively installed apps. The flow provides an access_token to each customer that is securely acquired in order to access the iSpot REST API.
OpenAPI specification
Originally known as the Swagger Specification, the OpenAPI Specification provides a standard for machine-readable interface files for describing, producing, consuming, and visualizing RESTful web services. Originally part of the Swagger framework, the OpenAPI Specification became a separate project in 2016, overseen by the OpenAPI Initiative, an open source collaborative project of the Linux Foundation.
P
Pagination
Pagination ensures that returned API responses are easier to handle. For example, a given response may retrieve hundreds of thousands of results that are likely not very useful. Pagination also allows you to request multiple pages in parallel. You can use pagination parameters to control the volume of information that is returned in an API response. For more information about pagination, see the iSpot API Integration Guide.
Python SDK
A resource that iSpot customers can download and use to access the iSpot REST API.
R
Rate limiting
Rate limiting controls the amount of incoming and outgoing network traffic. For example, if a particular API service is configured to allow 100 requests per minute, when a user exceeds that request limit, an error is triggered. Implementing rate limits allows for better data flow and data management. iSpot enforces rate limits to manage the network load. For information about rate limits that apply to iSpot REST API endpoints, see the iSpot API Integration Guide.
REST
REpresentational State Transfer (REST). REST is an architectural style for distributed hypermedia systems that was first presented by Roy Fielding in 2000 in his famous dissertation.
REST API
The iSpot REST API uses REpresentational State Transfer (REST) that allows for the use of multiple standards like HTTP, JSON, URL, and XML. The REST software architectural style defines a set of constraints for creating Web services that conform it, which are called RESTful Web services (RWS). RWS provides interoperability between computer systems on the internet.
Resource ID
The ID of a specific resource that a customer can reference in the iSpot REST API. Customers supply resource IDs that can be specific to a conversion site, a brand, an industry, and so on.
For example, a customer subscribed to TV Conversions with iSpot can to access the following endpoint that includes a unique resource ID: https://api.ispot.tv/v4/metrics/conversions/[id]? The customer’s resource ID is the same as the resource ID in the tracking pixel placed on the customer’s website. (Format: 'TC-####-#') The resource ID is tied to the customer’s primary TV brand, so all TV impressions and matched conversions are filtered appropriately in the API response.
T
TV Conversions data
TV Conversions data is available in the iSpot REST API. Note: Extra security in the iSpot API protects access to this first-party data for all of our clients.
