Logo
Become a Client

Data API – Basic Integration

Basic Integration is the simplest way to use the IDC API to fetch data. In this mode, IDC handles the heavy lifting of generating data exports for you. After each data refresh or product update, IDC’s systems automatically create exports of the full dataset for each product in your subscription. Your task is only to download those exports via the API. Basic Integration is ideal if you want all the data for your subscribed products as soon as it’s available, with no filtering or customization.

Key Characteristics

  • Full Data Exports: For every product you subscribe to, whenever IDC releases a new version, a complete data file (or files) is prepared and ready on the API. This includes all dimensions and measures – essentially the same data you would get from the IDC Query Tool UI export functionality.
  • List-and-Download Workflow: You use the API to list available files and then download them. There is no need to construct complex queries; you grab everything. This makes integration straightforward.
  • Recommended Approach: IDC generally recommends Basic Integration for most users to ensure you don’t miss any data. Only use Advanced Integration if you truly need to limit or customize the data per request.

How it works

List Available Exports:

Call the GET /exports endpoint without any parameters. The API responds with a JSON array describing each available export. For example, a single export entry looks like:

{
  "versionId": "39624_5_WW_MPT_2024Q1_1",
  "dataset": "Mobile Phone Tracker - Historical",
  "datasetId": 5,
  "exportId": "1234",
  "exportedAt": "2024-07-01 06:52:11",
  "status": "DATA_AVAILABLE",
  "pregenerated": "true",
  "files": [
    {
      "filename": "IDC_Mobile_Phone_Tracker_Historical_2024Q1_delivered-01-Jul-2024_1.csv.gz",
      "url": "https://www.idctracker.com/api/v3/exports/1234/files/1"
    },
    {
      "filename": "IDC_Mobile_Phone_Tracker_Historical_2024Q1_delivered-01-Jul-2024_2.csv.gz",
      "url": "https://www.idctracker.com/api/v3/exports/1234/files/2"
    }
  ]
}

(The above is an illustrative example.) Each object includes the product version identifier, a human-readable dataset name, an exportId, timestamp, and one or more file entries. The status will normally be "DATA_AVAILABLE" for these pre-generated exports – meaning they are ready to download.

Note: The pregenerated: “true” field indicates this export was prepared by IDC in advance (as opposed to a custom export request). Basic Integration deals with such pregenerated exports.

Determine New or Needed Files

Your integration logic should compare this list to what you’ve already downloaded. For example, store the filenames or export IDs you have processed, and find any new entries. IDC’s endpoint returns all available exports each time, so you may need to filter out those you’ve handled. Checking the exportedAt timestamp or unfamiliar exportId can help identify new data.

Download Files

For each file you need, use the provided url (or call the GET /exports/{exportId}/files/{fileId} endpoint) to download the file. Remember to include your API key in these requests and set Accept: application/zip to receive the binary GZIP data. Save the .csv.gz file and then extract it to get the CSV content. Each file will contain a portion of the dataset (some products may only have one file, others might have multiple parts).

Repeat Regularly

Basic integration is often implemented as a scheduled job. For example, you might run a script every hour or every day to hit the /exports list and fetch any new files. This ensures you capture updates shortly after they are released by IDC. IDC’s data releases follow their own schedules (different products have different refresh cycles like quarterly, semiannual, etc.), so a periodic check is a good strategy. IDC also usually sends out email notifications to designated contacts when new data is available or if there are changes, but your automated check will catch the files as well.

Example

As a simple scenario, let’s say you subscribe to the Worldwide PC Monitor Tracker. IDC updates this tracker quarterly. After a new quarter’s data is released, IDC will generate an export such as WW_PC_Monitor_Tracker_2024Q2_delivered-15-Aug-2024.csv.gz. Your script (using Basic Integration) would find this new file via GET /exports (seeing a new entry with versionId for 2024Q2), and then download the CSV.gz file(s). You then load that CSV into your database or analysis pipeline. By doing this consistently, you always have the latest tracker data shortly after IDC publishes it.

Basic Integration covers the majority of use cases where full datasets are needed. It’s straightforward and minimizes the number of API calls (just two calls per product: list and download). If you require data in a different shape – for example, only certain columns or a subset of countries or a custom currency – then consider using Advanced Integration, described next.