ConnectMeGuru LogoConnectMeGuru

API Documentation V2 — Product Feed & Affiliate Catalog

Last updated: November 3, 2026

ConnectMeGuru (CMG) — eSIM Product Feed API V2 Integration Guide

Welcome to the ConnectMeGuru eSIM Product Feed API (Version 2) documentation. This guide details how to integrate with our modern, enriched product catalog feed, authenticate requests, filter data packages by network features, and synchronize active travel eSIM plans with your storefront, price comparison engine, or mobile application.

1. Overview

The Product Feed API V2 provides a read-only, one-way JSON feed of active eSIM data plans, regional destination coverage, network carrier capabilities, tethering/hotspot compatibility, Fair Usage Policies (FUP), local IP internet breakout exits, and dynamically computed retail prices across 190+ countries and regions worldwide.

This API is designed specifically for high-performance catalog syndication and comparison engines. Ordering, ICCID provisioning, and wallet balance operations are handled through our dedicated partner transaction interfaces.

  • Protocol: HTTP/1.1 or HTTP/2 over TLS (HTTPS is required)
  • Method: GET
  • Content Type: application/json
  • Base Endpoint: 
    GET https://www.connectmeguru.com/api/products/aggregator/v2

2. Authentication & Public Access

API Key is Optional: Any affiliate partner, travel deal aggregator, price comparison engine, or developer can fetch the live product feed directly without requiring manual API key provisioning.

Public requests (omitting the key parameter) return active travel eSIM plans with standard global retail pricing rules applied.

If you have an authorized partner API key issued by ConnectMeGuru, pass your token in the key query parameter to retrieve custom wholesale markups, bespoke fixed buffers, or plan price overrides assigned to your partner account:

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

Note: Treat your private partner API key as a secure credential. Never expose it in client-side code or public version control repositories.

3. API Reference

Request Query Parameters

Parameter Type Required Description
key String No (Optional) Your unique partner API token (e.g. cmg_agg_...). If omitted or invalid, standard public retail pricing applies.
country String No Filter plans by destination country name, ISO 3166-1 alpha-2 code, or region (e.g. country=US, country=Japan, country=Europe).
productType String No Filter by plan traffic architecture model:
  • fixed — Standard fixed-data bundle (e.g. 10GB for 30 Days).
  • unlimitedDaily — Daily quota that resets every 24 hours, throttled until reset (e.g. 1GB/Day).
  • unlimited — Continuous high-speed unlimited connection.
  • daily — Daily reset bundle that cuts off without throttling.
supportsHotspot Boolean No Filter by personal hotspot / Wi-Fi tethering support: true or false.
excludeDaily Boolean No Set to true to exclude all daily reset plans from the feed.
excludeUnlimited Boolean No Set to true to exclude all unlimited data plans from the feed.
ref String No Partner affiliate referral code (e.g. demo-ab12). Automatically appended as ?ref=... to the productUrl field.
subId String No Sub-affiliate or downstream publisher tracking ID (e.g. pub99). Appended as &subId=... to productUrl.
limit Integer No Pagination limit (e.g. limit=50). Default: returns all matching plans.
offset Integer No Pagination offset index (e.g. offset=100). Default: 0.

HTTP Status Codes

Status Code Description Details
200 OK Success The product feed was compiled and returned successfully.
401 Unauthorized Authentication Failure Only returned if an invalid custom partner token is supplied. Omitted keys automatically use public access mode.
500 Internal Error Server Error Temporary internal processing exception.

4. Response Schema

A successful request returns a JSON object containing feed metadata and an array of matching plans.

Root Response Fields

  • success (Boolean): Indicates whether the request succeeded (always true on 200).
  • version (String): Feed version identifier (always "v2").
  • aggregator (String): Displays "Public Feed" or your registered partner name.
  • totalCount (Integer): Total number of plans matching the active query filters.
  • limit (Integer): Active pagination record limit.
  • offset (Integer): Starting index of the returned page.
  • plans (Array[Object]): Array of eSIM plan objects.

Plan Object Schema

Field Name Type Description
name String Commercial name of the eSIM package (e.g. "Japan 10GB 30Days").
packageCode String Unique identifier code for the plan.
productUrl String Direct purchase URL with affiliate tracking parameters (?ref=...&subId=...) automatically attached.
productType String Traffic model: "fixed", "unlimitedDaily", "unlimited", or "daily".
supportsHotspot Boolean true if the carrier profile supports personal hotspot / tethering with other devices.
isDaily Boolean true if the high-speed data allowance resets daily every 24 hours.
isUnlimited Boolean true if the plan provides unlimited data connectivity.
dataAmount Float / Integer Numeric data allowance volume expressed in dataUnit.
dataUnit String Unit of measurement: "GB" or "MB". Packages under 1 GB are mapped to MB (e.g. 500 MB).
dailyDataAmount Float / Integer / Null Daily allowance volume (e.g. 1 for 1GB/Day), or null for fixed plans.
dailyDataUnit String / Null Unit for daily allowance ("GB" or "MB"), or null.
totalDataAmount Float / Integer / Null Calculated total allowance over validity (e.g. 15 for 1GB/Day over 15 Days), or null for pure unlimited.
totalDataUnit String / Null Unit for total allowance ("GB" or "MB"), or null.
duration Integer Plan validity period.
durationUnit String Validity unit (always "DAY").
currency String Currency of the retail price (always "USD").
retailPrice Float Retail price in USD.
isThrottled Boolean true if data speed is throttled upon reaching high-speed quota.
fup Object Fair Usage Policy details:
  • hasFup (Boolean): True if FUP throttling applies.
  • policy (String / Null): Text explanation of FUP rule.
  • speedLimitKbps (Integer / Null): Throttled speed in kbps (e.g. 1024, 384).
  • speedLimitMbps (Float / Null): Throttled speed in Mbps (e.g. 1.0, 0.38).
  • resetPeriod (String / Null): Reset interval (e.g. "daily").
  • highSpeedAllowance (Float / Null): High-speed allowance before throttling.
  • highSpeedUnit (String / Null): High-speed tier unit ("GB" or "MB").
locationCodes Array[String] ISO 3166-1 alpha-2 destination country codes (e.g. ["FR", "DE", "IT"]). Global plans also include "GLOBAL".
locationNames Array[String] Full English country/destination names (e.g. ["France", "Germany", "Italy"]).
operator String Primary network operator name(s).
speed String Max network speeds (e.g. "3G/4G/5G").
isRegional Boolean true if package provides multi-country coverage.
regionalCode String / Null Regional identifier code (e.g. "EU-33"), or null.
isGlobal Boolean true if package provides global worldwide coverage.
internetBreakouts Array[String] Clean array of ISO 3166-1 alpha-2 country codes where cellular internet traffic exits the core network (e.g. ["GB", "NO"] or ["HK"]). An empty array [] is returned if specific breakout exit points are not defined.
networks Array[Object] Structured array per destination containing countryCode, countryName, and operators (with name and speed).

5. Sample Requests & Responses

cURL Examples

1. Public Feed (All plans for Japan):

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

2. Filter by Product Type (Unlimited Daily Reset Plans):

curl -X GET "https://www.connectmeguru.com/api/products/aggregator/v2?productType=unlimitedDaily&country=Europe" \\
     -H "Accept: application/json"

3. Filter by Hotspot Capability:

curl -X GET "https://www.connectmeguru.com/api/products/aggregator/v2?supportsHotspot=true&limit=20" \\
     -H "Accept: application/json"

4. Partner Custom Key Authentication:

curl -X GET "https://www.connectmeguru.com/api/products/aggregator/v2?key=cmg_agg_your_token_here&country=US" \\
     -H "Accept: application/json"

JSON Response Examples

A. Fixed Data Plan (productType: "fixed")

{
  "name": "Japan 10GB 30Days",
  "packageCode": "PKG-JP-10GB-30D",
  "productUrl": "https://www.connectmeguru.com/products/PKG-JP-10GB-30D?ref=demo-ab12&subId=pub99",
  "productType": "fixed",
  "supportsHotspot": true,
  "isDaily": false,
  "isUnlimited": false,
  "dataAmount": 10,
  "dataUnit": "GB",
  "dailyDataAmount": null,
  "dailyDataUnit": null,
  "totalDataAmount": 10,
  "totalDataUnit": "GB",
  "duration": 30,
  "durationUnit": "DAY",
  "currency": "USD",
  "retailPrice": 14.50,
  "isThrottled": false,
  "fup": {
    "hasFup": false,
    "policy": null,
    "speedLimitKbps": null,
    "speedLimitMbps": null,
    "resetPeriod": null,
    "highSpeedAllowance": null,
    "highSpeedUnit": null
  },
  "locationCodes": ["JP"],
  "locationNames": ["Japan"],
  "operator": "SoftBank / NTT Docomo",
  "speed": "4G/5G",
  "isRegional": false,
  "regionalCode": null,
  "isGlobal": false,
  "region": null,
  "internetBreakouts": ["JP"],
  "networks": [
    {
      "countryCode": "JP",
      "countryName": "Japan",
      "operators": [
        { "name": "SoftBank", "speed": "5G" },
        { "name": "NTT Docomo", "speed": "4G" }
      ]
    }
  ]
}

B. Unlimited Daily Reset Plan (productType: "unlimitedDaily")

{
  "name": "Europe 1GB/Day FUP384Kbps 15Days",
  "packageCode": "PKG-EU-1GBD-15D",
  "productUrl": "https://www.connectmeguru.com/products/PKG-EU-1GBD-15D?ref=demo-ab12&subId=pub99",
  "productType": "unlimitedDaily",
  "supportsHotspot": true,
  "isDaily": true,
  "isUnlimited": true,
  "dataAmount": 1,
  "dataUnit": "GB",
  "dailyDataAmount": 1,
  "dailyDataUnit": "GB",
  "totalDataAmount": 15,
  "totalDataUnit": "GB",
  "duration": 15,
  "durationUnit": "DAY",
  "currency": "USD",
  "retailPrice": 19.99,
  "isThrottled": true,
  "fup": {
    "hasFup": true,
    "policy": "1 GB/day high speed, then throttled to 384 Kbps",
    "speedLimitKbps": 384,
    "speedLimitMbps": 0.38,
    "resetPeriod": "daily",
    "highSpeedAllowance": 1,
    "highSpeedUnit": "GB"
  },
  "locationCodes": ["FR", "DE", "IT", "ES", "NL"],
  "locationNames": ["France", "Germany", "Italy", "Spain", "Netherlands"],
  "operator": "Multiple Networks",
  "speed": "4G/5G",
  "isRegional": true,
  "regionalCode": "EU-33",
  "isGlobal": false,
  "region": "EU-33",
  "internetBreakouts": ["GB", "NO"],
  "networks": [
    {
      "countryCode": "FR",
      "countryName": "France",
      "operators": [{ "name": "Orange", "speed": "5G" }]
    },
    {
      "countryCode": "DE",
      "countryName": "Germany",
      "operators": [{ "name": "Telekom", "speed": "5G" }]
    }
  ]
}

C. Pure Unlimited Plan (productType: "unlimited")

{
  "name": "USA Unlimited 7Days",
  "packageCode": "PKG-US-UNL-7D",
  "productUrl": "https://www.connectmeguru.com/products/PKG-US-UNL-7D?ref=demo-ab12&subId=pub99",
  "productType": "unlimited",
  "supportsHotspot": true,
  "isDaily": false,
  "isUnlimited": true,
  "dataAmount": 0,
  "dataUnit": "GB",
  "dailyDataAmount": null,
  "dailyDataUnit": null,
  "totalDataAmount": null,
  "totalDataUnit": null,
  "duration": 7,
  "durationUnit": "DAY",
  "currency": "USD",
  "retailPrice": 24.50,
  "isThrottled": false,
  "fup": {
    "hasFup": false,
    "policy": null,
    "speedLimitKbps": null,
    "speedLimitMbps": null,
    "resetPeriod": null,
    "highSpeedAllowance": null,
    "highSpeedUnit": null
  },
  "locationCodes": ["US"],
  "locationNames": ["United States"],
  "operator": "AT&T / T-Mobile",
  "speed": "4G/5G",
  "isRegional": false,
  "regionalCode": null,
  "isGlobal": false,
  "region": null,
  "internetBreakouts": ["US"],
  "networks": [
    {
      "countryCode": "US",
      "countryName": "United States",
      "operators": [
        { "name": "AT&T", "speed": "5G" },
        { "name": "T-Mobile", "speed": "5G" }
      ]
    }
  ]
}

D. Daily Reset Plan (productType: "daily")

{
  "name": "Thailand 500MB/Day 7Days",
  "packageCode": "PKG-TH-500MBD-7D",
  "productUrl": "https://www.connectmeguru.com/products/PKG-TH-500MBD-7D?ref=demo-ab12&subId=pub99",
  "productType": "daily",
  "supportsHotspot": true,
  "isDaily": true,
  "isUnlimited": false,
  "dataAmount": 500,
  "dataUnit": "MB",
  "dailyDataAmount": 500,
  "dailyDataUnit": "MB",
  "totalDataAmount": 3500,
  "totalDataUnit": "MB",
  "duration": 7,
  "durationUnit": "DAY",
  "currency": "USD",
  "retailPrice": 8.50,
  "isThrottled": false,
  "fup": {
    "hasFup": false,
    "policy": null,
    "speedLimitKbps": null,
    "speedLimitMbps": null,
    "resetPeriod": "daily",
    "highSpeedAllowance": null,
    "highSpeedUnit": null
  },
  "locationCodes": ["TH"],
  "locationNames": ["Thailand"],
  "operator": "AIS / TrueMove H",
  "speed": "4G/5G",
  "isRegional": false,
  "regionalCode": null,
  "isGlobal": false,
  "region": null,
  "internetBreakouts": ["TH"],
  "networks": [
    {
      "countryCode": "TH",
      "countryName": "Thailand",
      "operators": [
        { "name": "AIS", "speed": "5G" },
        { "name": "TrueMove H", "speed": "5G" }
      ]
    }
  ]
}

6. Integration Best Practices

  1. Caching & Synchronization: We recommend synchronizing once or twice every 24 hours. Wholesale inventories and prices update periodically, not in real-time.
  2. Direct Checkout Forwarding: Use the generated productUrl link to seamlessly transfer customers directly to checkout with your affiliate commission tracking pre-attached.

Need immediate help?

Our support engineers are available round-the-clock to assist with installation and network configurations.

Security Guarantee

ConnectMeGuru enforces secure TLS/SSL handshakes and direct vault tokens to ensure your transaction credentials and client wallets remain safe.