ConnectMeGuru (CMG) — eSIM Product Feed API Integration Guide

Welcome to the ConnectMeGuru eSIM Product Feed API documentation. This guide explains how to connect to the feed, authenticate requests, and synchronize active data plans with your storefront or app.

1. Overview

The Product Feed API provides a read-only, one-way JSON feed of active eSIM data plans, destination coverage, network carrier details, and retail prices.

This API is strictly used to display product information. Ordering, provisioning, and top-up transactions cannot be performed through this endpoint.

Protocol: HTTP/1.1 over TLS (HTTPS is required)
Method: GET
Content Type: application/json

Base Endpoint:

GET https://www.connectmeguru.com/api/products/aggregator

2. Authentication

Access to the product feed is secured via a unique query token (key) provided by the ConnectMeGuru administrator.

To authenticate, append the key parameter to your request:

GET https://www.connectmeguru.com/api/products/aggregator?key=YOUR_UNIQUE_API_KEY

Warning: Treat your API key as a secure credential. Do not expose it in client-side code or commit it to public version control repositories.

3. API Reference

Request Query Parameters

Parameter	Type	Required	Description
`key`	String	Yes	Your unique API token (e.g., `cmg_agg_...`).
`ref`	String	No	The partner's affiliate referral code (e.g., `demo-ab12`). When provided, it automatically appends the referral tracking parameter to the `productUrl` field in the response.
`subId`	String	No	The sub-affiliate or actual publisher tracking ID (e.g., `pub99`). When provided alongside `ref`, it is dynamically appended as a parameter (`&subId=...`) to the `productUrl` field in the response to track downstream publisher earnings.

HTTP Status Codes

Status Code	Description	Reason
`200 OK`	Success	The feed was compiled and returned successfully.
`401 Unauthorized`	Authentication Failure	The `key` parameter was omitted, expired, or is invalid.
`500 Internal Error`	Server Failure	A temporary issue occurred on the server. Try again later.

4. Response Schema

A successful request returns a JSON object containing the metadata and an array of available plans.

Response JSON Fields

success (Boolean): Indicates if the operation was successful.
aggregator (String): Your registered aggregator name.
plans (Array): List of available eSIM data plans.

Plan Object Schema

Field Name	Type	Description
`name`	String	Commercial name of the eSIM data package.
`packageCode`	String	Unique identifier code for the plan.
`productUrl`	String	Ready-made storefront link pointing directly to the plan details page. If a referral code and sub-ID were passed in the request, they are dynamically appended to this URL.
`dataAmount`	Float/Integer	Numeric data allowance volume. Expressed in the unit specified by the `dataUnit` field.
`dataUnit`	String	The unit of measurement for `dataAmount`: either `"GB"` or `"MB"`. Plans with allowances under 1 GB are automatically mapped to MB (e.g., 500 MB).
`duration`	Integer	Package validity period in days once activated.
`currency`	String	The fixed currency code of the retail price (always `"USD"`).
`locationCodes`	Array[String]	ISO 2-letter country codes where the eSIM operates (e.g., `["DE", "FR"]`).
`locationNames`	Array[String]	Fully resolved English country names matching the coverage location codes (e.g., `["Germany", "France"]`).
`operator`	String	Supported network carrier(s) (e.g., `Orange, T-Mobile`).
`speed`	String	Network speed capabilities (e.g., `3G/4G/5G`).
`retailPrice`	Float	The retail purchase price in the specified `currency`.
`fupSpeedLimit`	Integer / Null	The throttled internet speed limit in kbps under Fair Usage Policy (e.g., `1024` for 1Mbps, `128` for 128Kbps), or `null` if the plan does not have FUP throttling.
`networks`	Array[Object]	Country-level carrier network details containing `countryCode` (String), `countryName` (String), and `operators` (Array of objects with `name` and `speed`).

5. Sample Request & Response

cURL Example

curl -X GET "https://www.connectmeguru.com/api/products/aggregator?key=cmg_agg_123456abcdef&ref=demo-ab12&subId=pub99"      -H "Accept: application/json"

JSON Response Example

{
  "success": true,
  "aggregator": "CMG Aggregator",
  "plans": [
    {
      "name": "Europe 10GB 30-Day eSIM",
      "packageCode": "PKG-EU-10GB-30D",
      "productUrl": "https://www.connectmeguru.com/products/PKG-EU-10GB-30D?ref=demo-ab12&subId=pub99",
      "dataAmount": 10.0,
      "dataUnit": "GB",
      "duration": 30,
      "currency": "USD",
      "locationCodes": ["FR", "DE", "IT", "ES"],
      "locationNames": ["France", "Germany", "Italy", "Spain"],
      "operator": "Orange, Movistar, Vodafone",
      "speed": "4G/5G",
      "retailPrice": 18.50,
      "fupSpeedLimit": null,
      "networks": [
        {
          "countryCode": "FR",
          "countryName": "France",
          "operators": [
            { "name": "Orange", "speed": "5G" }
          ]
        },
        {
          "countryCode": "DE",
          "countryName": "Germany",
          "operators": [
            { "name": "T-Mobile", "speed": "5G" }
          ]
        },
        {
          "countryCode": "IT",
          "countryName": "Italy",
          "operators": [
            { "name": "WindTre", "speed": "4G" }
          ]
        },
        {
          "countryCode": "ES",
          "countryName": "Spain",
          "operators": [
            { "name": "Movistar", "speed": "5G" },
            { "name": "Vodafone", "speed": "4G" }
          ]
        }
      ]
    },
    {
      "name": "Singapore 1GB/Day FUP1Mbps",
      "packageCode": "PK1LYCQ40",
      "productUrl": "https://www.connectmeguru.com/products/PK1LYCQ40?ref=demo-ab12&subId=pub99",
      "dataAmount": 1,
      "dataUnit": "GB",
      "duration": 1,
      "currency": "USD",
      "locationCodes": ["SG"],
      "locationNames": ["Singapore"],
      "operator": "StarHub 5G",
      "speed": "3G/4G/5G",
      "retailPrice": 1.15,
      "fupSpeedLimit": 1024,
      "networks": [
        {
          "countryCode": "SG",
          "countryName": "Singapore",
          "operators": [
            { "name": "StarHub", "speed": "5G" }
          ]
        }
      ]
    }
  ]
}

6. Integration Best Practices

Sync Frequency: We recommend caching the plans list and synchronizing once or twice a day. Product catalogs do not change in real-time.
Filtering: Use locationCodes to map coverage indicators in your own search or filtering systems.
One-Way Integration: Since this is a display-only product sync API, no checkout, purchase, or order transaction operations can be executed against this feed.

Affiliate Aggregator API Documentation