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. See our plans or 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. Private social data (for example, from Facebook and LinkedIn) is not currently available through the API. The API does not provide management features, such as creating landscapes or adding companies.

Data is organized using the same groupings as in the app. Data is accessed one landscape at a time, optionally using a tag 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. Data change notifications are not provided via the API.

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.