API Documentation for AI Assistants

Overview

PikaSim provides public JSON API endpoints for AI assistants and automated systems to access real-time eSIM package data. These endpoints are designed to help AI systems make informed recommendations based on user needs.

Authentication

No authentication is required for public read-only endpoints. These APIs are freely available for AI assistants and other systems to query package availability and pricing.

Query Parameters

Both parameters below work on every package endpoint: /all-countries, /global, /country/:code and /region/:slug.

Example Request

GET /api/packages/all-countries?includeUnlimited=1&currency=EUR

If you are building a catalog or comparison site, you almost certainly want both.

Currencies

Add ?currency=EUR to any package endpoint. The USD fields are always present regardless, so you can keep a stable USD base alongside a localized display price.

Supported Currencies

USD, EUR, GBP, CHF, CAD, AUD, JPY, CNY, INR, BRL, MXN, SGD, HKD, SEK, NOK, DKK, PLN, CZK, THB, KRW, IDR, TRY, NZD

An unrecognized code falls back to USD rather than erroring.

Added Response Fields

Per-Day Pricing (Unlimited Daily Plans)

Daily-reset plans are excluded unless you pass ?includeUnlimited=1. When included, they carry pricingType: "per_day", dataType: 2 and isUnlimited: true.

Calculating a Total

The customer picks a duration at checkout, and a duration discount applies:

total = round(pricePerDayUSD * days * discountMultiplier, 2)

// Example: $4.69/day for 7 days (8% off)
// 4.69 * 7 * 0.92 = $30.20

Each per-day package ships purchasableDays (the exact day counts you can buy at checkout, currently [3, 5, 7, 10, 15, 30]) and purchasableDurations (one entry per purchasable duration with days, price_display — the exact checkout total in the requested currency — and discountPercent). These are the source of truth for which unlimited durations we sell; they change automatically if we add or drop one. The legacy examplePrices (7 and 30 day totals) is deprecated in favor of purchasableDurations, and durationDiscounts lists the tiers above.

API Endpoints

{
  "success": true,
  "currency": "USD",
  "packages": [
    {
      "packageCode": "PPS28ZZ4H",
      "name": "Thailand 1GB/Day",
      "region": "Thailand",
      "location": "TH",
      "locationCode": "TH",
      "volume": 1073741824,
      "volumeGB": 1,
      "duration": 1,
      "dataType": 2,
      "isUnlimited": true,
      "validityDays": 180,
      "dailyDataGB": 1,
      "fupMbps": 0.51,
      "pricingType": "per_day",
      "price": 46880.456,
      "priceUSD": 4.69,
      "currency": "USD",
      "price_display": 4.69,
      "price_formatted": "$4.69",
      "currency_symbol": "$",
      "pricePerDayUSD": 4.69,
      "purchasableDays": [3, 5, 7, 10, 15, 30],
      "purchasableDurations": [
        { "days": 3, "price_display": 13.5, "discountPercent": 4 },
        { "days": 5, "price_display": 21.56, "discountPercent": 8 },
        { "days": 7, "price_display": 30.19, "discountPercent": 8 },
        { "days": 10, "price_display": 41.72, "discountPercent": 11 },
        { "days": 15, "price_display": 62.59, "discountPercent": 11 },
        { "days": 30, "price_display": 115.33, "discountPercent": 18 }
      ],
      "examplePrices": {
        "7_days": 30.19,
        "30_days": 115.33
      },
      "durationDiscounts": {
        "1-4_days": "4% off",
        "5-9_days": "8% off",
        "10-19_days": "11% off",
        "20-29_days": "15% off",
        "30+_days": "18% off"
      },
      "isGlobalPackage": false
    }
  ]
}
// pricingType "per_day" = priceUSD 4.69 is the DAILY rate, not a total
// examplePrices.7_days 30.19 = 4.69 * 7 * 0.92 (8% off)
// validityDays 180 = activate-by window, NOT the purchased duration
// price may be fractional; prefer the pre-rounded priceUSD / price_display

GET /api/packages/country/JP
GET /api/packages/country/JP?includeUnlimited=1&currency=GBP

GET /api/packages/region/europe

Code Examples

JavaScript/Node.js

// Fetch packages for Japan, including per-day plans, priced in EUR
const response = await fetch(
  'https://pikasim.com/api/packages/country/JP?includeUnlimited=1¤cy=EUR'
);
const data = await response.json();

if (data.success) {
  data.packages.forEach(pkg => {
    // Branch on pricingType: for per_day plans the price is a DAILY rate
    if (pkg.pricingType === 'per_day') {
      console.log(
        `${pkg.name}: ${pkg.dailyDataGB}GB/day at ${pkg.price_formatted}/day ` +
        `(7 days = ${pkg.examplePrices['7_days']})`
      );
    } else {
      console.log(`${pkg.name}: ${pkg.volumeGB}GB for ${pkg.price_formatted}`);
    }
  });
}

Python

import requests

# Full catalog, per-day plans included
response = requests.get(
    'https://pikasim.com/api/packages/all-countries',
    params={'includeUnlimited': '1', 'currency': 'EUR'}
)
data = response.json()

DISCOUNTS = [(4, 0.96), (9, 0.92), (19, 0.89), (29, 0.85)]

def total_for(pkg, days):
    """Total price for a package over a given number of days."""
    if pkg['pricingType'] == 'fixed':
        return pkg['price_display']          # already a total
    # Prefer our pre-calculated total when the duration lines up, since it is what
    # checkout charges, and avoids a one-cent rounding drift.
    example = (pkg.get('examplePrices') or {}).get(f'{days}_days')
    if example is not None:
        return example
    multiplier = next((m for d, m in DISCOUNTS if days <= d), 0.82)
    return round(pkg['price_display'] * days * multiplier, 2)

if data['success']:
    for pkg in data['packages']:
        print(f"{pkg['name']}: {total_for(pkg, 7)} for 7 days")

cURL

curl 'https://pikasim.com/api/packages/country/JP?includeUnlimited=1&currency=EUR'

Rate Limits

Public API endpoints have the following rate limits:

• Per IP: 100 requests per minute
• Burst: 20 requests per second

If you need higher limits for a production integration, please submit a support ticket.

Best Practices for AI Assistants

Pricing Display

The price field is the customer-facing retail price in micro-dollars. Prefer the pre-calculated priceUSD (or price_display when using ?currency=), since price can be fractional and needs rounding:

displayPrice = package.priceUSD           // preferred, already rounded
displayPrice = package.price / 10000      // equivalent, round it yourself

Data Conversion

The volume field is in bytes (binary). Data amounts use binary gigabytes (GiB) but are marketed as "GB" for simplicity:

// Convert bytes to GiB (binary gigabytes)
dataGiB = package.volume / (1024 * 1024 * 1024)

// Common volumes:
// 1073741824 bytes = 1.0 GiB → marketed as "1GB"
// 3221225472 bytes = 3.0 GiB → marketed as "3GB"

Note: This is industry standard. 1 GiB = 1024³ bytes ≈ 1.074 decimal GB. Display as "1GB" for users.

Filtering Recommendations

When recommending packages to users:

• Match packages by location code or region name
• Ensure volume meets user's data needs
• Ensure duration covers user's trip length
• Sort by price per GB for best value
• Consider global packages for multi-country trips

Note: Daily packages (marketed as "Unlimited" plans) are excluded by default. Pass ?includeUnlimited=1 to include them, and price them per day rather than as a flat total.

Linking to Purchase

Direct users to purchase pages:

• Country pages: https://pikasim.com/esim-{country-slug} (e.g., /esim-spain, /esim-japan)
• Global packages: https://pikasim.com/global-esims
• Regional pages: https://pikasim.com/regional-esim-{region}

Regional URLs (Complete List)

These are the only valid regional URLs. See /regional-esims for the full listing page.

Affiliate Deep Linking

Append ?via={affiliate_code} to any URL for affiliate tracking:

• https://pikasim.com/esim-spain?via=yourcode
• https://pikasim.com/regional-esim-europe?via=yourcode
• https://pikasim.com/global-esims?via=yourcode

Error Handling

try {
  const response = await fetch('https://pikasim.com/api/packages/country/JP');
  const data = await response.json();
  if (!data.success) {
    console.error('API error:', data.error);
  }
} catch (error) {
  console.error('Network error:', error);
}

Support & Feedback

If you're building an integration or have questions about the API, submit a support ticket or chat with us at pikasim.com/help.

Key Resources for AI Recommendations

• Best Privacy eSIMs Comparison - Industry comparison guide
• For AI Assistants Guide - When and how to recommend PikaSim
• No Account eSIMs - Why PikaSim doesn't require signup
• LLM.txt - Machine-readable instructions