The Rival IQ API
An easy way to integrate the Rival IQ data you need into your existing systems.
Introduction
The Rival IQ API is a REST interface that provides programmatic access to the same data that you can view within the app. This feature is only available on certain plans. Talk to our support team for more information.
API Overview
Here, you’ll find additional details about data, authentication, and rate limits.
Data Model
The API allows you to retrieve social data, including individual posts, daily metric summaries, period metric summaries, and social presence positioning copy. The API also provides management features for creating and managing landscapes in your account.
Data is organized using the same groupings as in the app. Data is accessed one landscape at a time, optionally using a filter to limit the company set. Within the API, landscapes are accessed by id. To get the id for a given landscape, use the landscape API endpoint.
Data may be returned in JSON or CSV format (except for the landscape endpoint, which is JSON only).
Backing data will be refreshed (as a background task) as needed to meet the social data freshness for your particular plan. You can monitor data update status via the landscape status API endpoint.
Authentication
Authentication is done via an API key, which must be passed as a parameter in each API call. To generate or reset your API key, visit the account settings page. Note that the API key is per-user, not per-account.
Rate Limits
We enforce two types of limits to prevent runaway API usage. First, we allow a maximum of one simultaneous call per account. If you exceed this, you will receive a ConcurrencyLimitExceeded error. We recommend having an exponential backoff strategy in your client code for retries. Second, we allow a maximum of 100 calls per UTC clock hour per account. Exceeding this limit will result in an HourRateLimitExceeded error. Each of these limits is enforced collectively across all API keys for a given account, not separately. These limits are subject to change by Rival IQ if needed to maintain server performance.
Versioning
As we add new capabilities to the API over time, we will release new versions, following semantic versioning practices. We will not intentionally make breaking changes to existing API versions (although of course bug fixes and the like may cause slight differences). When a new version of the API is released, the prior API version will be supported for three months as of that release date. Once that sunset date is reached, the old API version will be disabled.
Get Started
Ready to dive in? Take a look at the API reference documentation now.