Skip to content

API-REFERENCE.md

Latest commit

 

History

History
497 lines (362 loc) · 13 KB

API-REFERENCE.md

File metadata and controls

497 lines (362 loc) · 13 KB

API Reference

Complete reference for the Destinations API integration used by this Claude Code plugin.

Base Configuration

  • Base URL: https://destinations-api.telecomsxchange.com
  • Protocol: HTTPS only
  • Authentication: None required (open access)
  • Rate Limit: 100 requests per minute
  • Response Format: JSON

Endpoints

1. Search Destinations

Search for telecom destinations using various filters.

Endpoint: GET /search/

Query Parameters:

Parameter Type Required Description Example
prefix string No Phone number prefix (digits only) 1, 855, 44
country_name string No Country name (UPPERCASE) CAMBODIA, UNITED STATES
description string No Network description/type Mobile, Fixed, VoIP
mccmnc string No Mobile Country/Network Code 45601, 310120
page integer No Page number for pagination 1, 2, 3
limit integer No Results per page (1-1000) 100 (default), 500, 1000

Response Schema:

{
  "count": 1543,
  "next": "https://destinations-api.telecomsxchange.com/search/?page=2",
  "previous": null,
  "results": [
    {
      "id": 12345,
      "prefix": "85512",
      "country_name": "CAMBODIA",
      "description": "Metfone Mobile",
      "mccmnc": "45608",
      "interval_1": 60,
      "interval_n": 1,
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2025-03-20T14:45:00Z"
    }
  ]
}

Response Fields:

Field Type Description
count integer Total number of matching results
next string/null URL for next page of results
previous string/null URL for previous page of results
results array Array of destination objects
results[].id integer Unique destination identifier
results[].prefix string Phone number prefix (country code + area code)
results[].country_name string Country name (UPPERCASE)
results[].description string Network/carrier description
results[].mccmnc string Mobile Country Code + Mobile Network Code
results[].interval_1 integer Initial billing interval in seconds
results[].interval_n integer Subsequent billing interval in seconds
results[].created_at datetime Record creation timestamp (ISO 8601)
results[].updated_at datetime Last update timestamp (ISO 8601)

Example Requests:

# Search by country
GET /search/?country_name=CAMBODIA

# Search by prefix
GET /search/?prefix=855

# Search by MCC/MNC
GET /search/?mccmnc=45601

# Search with pagination
GET /search/?country_name=UNITED%20STATES&limit=500&page=2

# Combined search
GET /search/?country_name=CAMBODIA&description=Mobile&limit=100

Status Codes:

  • 200 OK - Successful response with results
  • 400 Bad Request - Invalid query parameters
  • 429 Too Many Requests - Rate limit exceeded
  • 500 Internal Server Error - Server error

2. Billing Updates (Historical)

Retrieve historical billing increment changes filtered by year, country, or change type.

Endpoint: GET /updates/

Query Parameters:

Parameter Type Required Description Example
year integer No Filter by year 2024, 2025
country string No Filter by country name (UPPERCASE) CAMBODIA
change_type string No Filter by change type increase, decrease, improved, mixed
limit integer No Results per page (1-500) 100 (default)
page integer No Page number for pagination 1, 2, 3

Response Schema:

{
  "count": 245,
  "next": "https://destinations-api.telecomsxchange.com/updates/?page=2",
  "previous": null,
  "results": [
    {
      "id": 5678,
      "prefix": "85512",
      "country_name": "CAMBODIA",
      "description": "Metfone Mobile",
      "mccmnc": "45608",
      "old_interval_1": 60,
      "old_interval_n": 60,
      "new_interval_1": 60,
      "new_interval_n": 1,
      "change_type": "improved",
      "change_date": "2025-03-20",
      "notes": "Billing improved to per-second increments"
    }
  ]
}

Response Fields:

Field Type Description
change_type string Type of change: improved, mixed, increase, decrease
old_interval_1 integer Previous initial billing interval (seconds)
old_interval_n integer Previous subsequent billing interval (seconds)
new_interval_1 integer New initial billing interval (seconds)
new_interval_n integer New subsequent billing interval (seconds)
change_date date Date when billing change occurred (ISO 8601)
notes string Additional information about the change

Example Requests:

# Updates for 2025
GET /updates/?year=2025

# Improvements only
GET /updates/?change_type=improved

# Country-specific updates
GET /updates/?country=CAMBODIA&year=2025

# All deteriorations
GET /updates/?change_type=decrease

3. Recent Billing Updates

Retrieve billing changes from the last N days (1-365 days).

Endpoint: GET /updates/recent

Query Parameters:

Parameter Type Required Description Example
days integer No Number of days to look back (1-365) 30 (default), 7, 90
limit integer No Results per page (1-500) 100 (default)

Response Schema:

Same as /updates/ endpoint.

Example Requests:

# Last 30 days (default)
GET /updates/recent

# Last 7 days
GET /updates/recent?days=7

# Last 90 days with higher limit
GET /updates/recent?days=90&limit=500

4. Updates Summary

Retrieve aggregated statistics about billing changes.

Endpoint: GET /updates/summary

Query Parameters:

Parameter Type Required Description Example
year integer No Filter summary by year 2025
days integer No Summary for last N days 30, 90

Response Schema:

{
  "total_updates": 1543,
  "improvements": 987,
  "deteriorations": 234,
  "mixed_changes": 322,
  "affected_countries": 156,
  "affected_prefixes": 1234,
  "period": "2025-01-01 to 2025-12-31",
  "top_improving_countries": [
    {"country": "CAMBODIA", "count": 45},
    {"country": "THAILAND", "count": 38}
  ],
  "top_deteriorating_countries": [
    {"country": "EXAMPLE_COUNTRY", "count": 12}
  ]
}

Response Fields:

Field Type Description
total_updates integer Total number of billing updates
improvements integer Number of improved billing increments
deteriorations integer Number of deteriorated billing increments
mixed_changes integer Number of mixed/neutral changes
affected_countries integer Number of countries with changes
affected_prefixes integer Number of prefixes with changes
period string Date range covered by summary
top_improving_countries array Countries with most improvements
top_deteriorating_countries array Countries with most deteriorations

Example Requests:

# Summary for 2025
GET /updates/summary?year=2025

# Summary for last 90 days
GET /updates/summary?days=90

# Overall summary
GET /updates/summary

Billing Increment Format

The API uses a two-part billing format: interval_1/interval_n

Format Breakdown

Format interval_1 interval_n Meaning
1/1 1 second 1 second Per-second billing from start (best)
60/1 60 seconds 1 second 60s minimum, then per-second (better)
30/30 30 seconds 30 seconds 30s increments throughout (good)
60/60 60 seconds 60 seconds Per-minute billing (standard)
180/180 180 seconds 180 seconds 3-minute increments (less favorable)

Cost Examples

For a 2 minute 15 second (135 second) call:

Billing Calculation Charged Time Notes
1/1 135 × 1s 135 seconds Most favorable
60/1 60 + (75 × 1s) 135 seconds Same as 1/1 after minimum
60/60 60 + (60 × 2) 180 seconds Rounded to 3 minutes
180/180 180 180 seconds Rounded to full 3 minutes

Key Insight: Lower interval_1 and interval_n values = better cost control

Rate Limiting

Limits

  • Rate: 100 requests per minute
  • Window: Rolling 60-second window
  • Response Header: X-RateLimit-Remaining (if available)

Best Practices

  1. Batch requests - Use pagination with higher limits (limit=1000) instead of multiple small requests
  2. Cache responses - Store frequently accessed data locally
  3. Implement retry logic - Handle 429 responses with exponential backoff
  4. Monitor usage - Track your request count per minute

Rate Limit Response

When rate limit is exceeded:

{
  "error": "Rate limit exceeded",
  "detail": "Maximum 100 requests per minute allowed",
  "retry_after": 45
}

Status Code: 429 Too Many Requests

Error Handling

Error Response Format

{
  "error": "Error type",
  "detail": "Detailed error message",
  "field": "parameter_name"
}

Common Error Codes

Status Code Error Type Description Solution
400 Bad Request Invalid query parameters Check parameter format and values
404 Not Found No results match query Broaden search criteria
429 Rate Limit Too many requests Wait before retrying
500 Server Error Internal API error Retry after delay

Pagination

All list endpoints support pagination.

Pagination Parameters

Parameter Description Default Max
page Page number 1 N/A
limit Results per page 100 1000 (search), 500 (updates)

Pagination Response

{
  "count": 5432,
  "next": "https://api.example.com/search/?page=2&limit=100",
  "previous": null,
  "results": [...]
}

Iterating Through Pages

# Page 1
GET /search/?country_name=UNITED%20STATES&limit=1000

# Page 2 (use 'next' URL from response)
GET /search/?country_name=UNITED%20STATES&limit=1000&page=2

Usage Examples

Complete Workflow Examples

Example 1: Find Best Billing for Destination

# Step 1: Search all carriers for Cambodia mobile
GET /search/?country_name=CAMBODIA&description=Mobile&limit=100

# Step 2: Filter results by billing
# Look for interval_1=1 or interval_n=1 in results

# Step 3: Check recent billing changes
GET /updates/recent?days=30

# Step 4: Verify no recent deteriorations
# Filter response for Cambodia + specific MCC/MNC

Example 2: Validate Phone Number

# Step 1: Extract prefix from +855 12 345 6789 → "85512"
GET /search/?prefix=85512

# Step 2: Verify result matches expected country
# Check response[0].country_name == "CAMBODIA"

# Step 3: Confirm carrier assignment
# Check response[0].mccmnc and description

Example 3: Track Market Trends

# Step 1: Get summary statistics
GET /updates/summary?year=2025

# Step 2: Get detailed improvements
GET /updates/?year=2025&change_type=improved&limit=500

# Step 3: Compare to previous year
GET /updates/summary?year=2024

Data Formats

Phone Number Prefix

  • Format: Digits only, no symbols
  • Example: 855 (Cambodia), 44 (UK), 1212 (US New York)
  • Length: 1-15 digits
  • Standard: E.164 compliant

MCC/MNC Format

  • Format: Concatenated MCC + MNC
  • MCC: 3 digits (Mobile Country Code)
  • MNC: 2-3 digits (Mobile Network Code)
  • Example: 45601 = MCC 456 (Cambodia) + MNC 01 (Cellcard)

Country Names

  • Format: UPPERCASE text
  • Example: CAMBODIA, UNITED STATES, UNITED KINGDOM
  • Special Cases: Multi-word countries use spaces

Timestamps

  • Format: ISO 8601
  • Example: 2025-10-12T14:30:00Z
  • Timezone: UTC (Z suffix)

Integration Notes

Using with Claude Code Plugin

The plugin automatically handles:

  • URL construction with proper encoding
  • Rate limit tracking via hooks
  • Response parsing and formatting
  • Error handling and retry logic

WebFetch Tool Integration

All API requests use the WebFetch tool:

WebFetch({
  url: "https://destinations-api.telecomsxchange.com/search/?prefix=855",
  prompt: "Extract and return all destination records with prefix, country_name, description, mccmnc, interval_1, and interval_n"
})

Further Resources

  • OpenAPI Specification: https://destinations-api.telecomsxchange.com/openapi.json
  • API Documentation: https://destinations-api.telecomsxchange.com/docs
  • Rate Limit Status: Check response headers or contact API maintainers
  • Data Updates: API data is continuously updated; check updated_at field

Last Updated: 2025-10-12 API Version: 1.0 Plugin Version: 1.0.0