Data API Implementation Walkthrough

It is important to remember that the primary format to retrieve the data sets through the REST API is a file. Once you will retrieve the file(s) you can ingest the dataset from the file.

Each file is a GZIP compressed file containing a single CSV file (.czv.gz), e.g.: IDC_Quarterly_Workstation_Tracker_-_Final_Historical_2023Q3_delivered-08-Nov-2023_1.csv.gz

The first row of the CSV file always contains the column captions.

The size of the exported files varies from couple of MBs to tens of GBs, depending on the size of the product.

One product export yields one or more files. This is due to the nature of the datasets. For example, some products are tracked by Segment and Channel in two separate datasets and would be delivered in two separate files.

IDC’s API uses API keys to authenticate requests. Every request to the Query Tool API must include a valid API key that is associated with your organization’s account. Here’s what you need to know:

• Obtaining an API Key: IDC will provide your API key during the onboarding process. This is typically a lengthy alphanumeric string. If you haven’t received a key, refer to Setting up API Access to obtain one.
• Using the API Key: Include the API key in the HTTP headers of each request. Specifically, set the header x-api-key to your API key value. For example:
  x-api-key: ABC123_YOUR_KEY_XYZ
• Additional Headers: Besides the API key, you should set Content-Type: application/json for requests with bodies (e.g. POST requests) and can specify Accept to indicate the desired response format (usually application/json, or application/zip when downloading files).
• Key Security: Treat your API key as a secret. Do not embed it in client-side code or anywhere it could be exposed publicly. If you suspect your key is compromised, notify IDC support – they can rotate your credentials.
• Expiration and Renewal: API keys may have an expiration or may be revoked if unused for long periods. If you receive a 401 Unauthorized error and you are sending the key correctly, it could indicate an invalid or expired API key. Request a new key from IDC if needed.

Once authenticated, you can access the various endpoints described below. All responses are JSON unless otherwise noted. For testing, you can use tools like CURL or Postman by adding the x-api-key header to your requests.

The core endpoints of the Query Tool API v3 are summarized here (with details in subsequent sections):

• GET /api/v3/exports – List available exports. Returns a list of all data exports available to your account at the time of the request (including pre-generated full dataset exports and any custom exports you’ve triggered).
• GET /api/v3/exports/{exportId}/files/{fileId} – Download a specific file. Each export can contain one or more file parts; this endpoint downloads a file (GZIP CSV) given an export ID and file ID. (Note: the file URLs provided in the exports list are the same endpoints).
• GET /api/v3/products – List available products. Returns metadata for each product (data product) you have access to, including the latest version ID, product name, and publication date. Use this to discover Version IDs for advanced queries.
• GET /api/v3/products/{versionId}/dimensions – Get dimensions for a product. Returns a list of dimension names for the given product version (e.g., [“Region”, “Year”, “Vendor”, …]).
• GET /api/v3/products/{versionId}/measures – Get measures for a product. Returns a list of measure names (metrics) for the product version (e.g., [“Units”, “Value”, …]).
• GET /api/v3/products/{versionId}/currencies – Get supported currencies. Returns a list of currency names or codes available for the product (if currency conversion is supported). If empty or not used, USD is default.
• GET /api/v3/products/{versionId}/dimensions/{dimensionName}/values – Get valid values for a dimension. Returns a list of all values for a given dimension, for that product version (e.g., all years available). This helps in constructing filters for queries. This functionality is limited to time-dimensions only (e.g., Quarter, Year, etc., depending on product’s granularity).
• POST /api/v3/exports – Register a custom export (Advanced Integration). Accepts a JSON body defining a query (selected dimensions, measures, filters, currency) and a Version ID, and initiates an export job. Returns an exportId and initial status.
• GET /api/v3/exports/{exportId} – Check export status. Returns the status and metadata of a specific export (including file URLs if ready).
• (Other endpoints: There may be additional endpoints for user account info or other features not listed here, but the above cover the primary data retrieval workflow.)

See the OpenAPI specification here: https://idctracker.com/v3/api-docs.yaml

In the next two sections, we explain how to use these endpoints in two integration modes: Data API & Basic Integration (pre-generated full data downloads) and Data API & Advanced Integration(custom queries).

Basic Integration is an ideal solution for downloading the latest revision of the entire dataset.

Advanced Integration allows to limit what data points you want to download by specifying a query.