Pagination

How to paginate through large result sets

Several telco.dev API endpoints return paginated results. This guide explains how to work with pagination effectively.

Paginated Endpoints

The following endpoints support pagination:

• GET /v1/npa/:npa - Area code exchanges
• GET /v1/search - Search results
• GET /v1/carriers - Carrier list

Pagination Parameters

Response Format

Paginated responses include a pagination object:

{
  "results": [...],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "total": 847
  }
}

Basic Pagination

First Page

curl -H "X-API-Key: your-key" \
  "https://api.telco.dev/v1/npa/415?limit=20"

Second Page

curl -H "X-API-Key: your-key" \
  "https://api.telco.dev/v1/npa/415?limit=20&offset=20"

Third Page

curl -H "X-API-Key: your-key" \
  "https://api.telco.dev/v1/npa/415?limit=20&offset=40"

Iterating Through All Pages

JavaScript

async function getAllResults(baseUrl, apiKey) {
  const allResults = [];
  const limit = 100; // Max allowed
  let offset = 0;
  let total = null;

  while (total === null || offset < total) {
    const url = `${baseUrl}?limit=${limit}&offset=${offset}`;
    const response = await fetch(url, {
      headers: { "X-API-Key": apiKey }
    });

    const data = await response.json();

    // Handle different response shapes
    const results = data.results || data.exchanges || data.carriers;
    allResults.push(...results);

    total = data.pagination.total;
    offset += limit;

    // Optional: Add delay to avoid rate limits
    if (offset < total) {
      await new Promise(r => setTimeout(r, 100));
    }
  }

  return allResults;
}

// Usage
const allExchanges = await getAllResults(
  "https://api.telco.dev/v1/npa/415",
  process.env.TELCO_API_KEY
);

console.log(`Fetched ${allExchanges.length} exchanges`);

Python

import requests
import time
import os

def get_all_results(base_url, api_key):
    all_results = []
    limit = 100
    offset = 0
    total = None

    while total is None or offset < total:
        response = requests.get(
            base_url,
            params={"limit": limit, "offset": offset},
            headers={"X-API-Key": api_key}
        )
        response.raise_for_status()
        data = response.json()

        # Handle different response shapes
        results = data.get("results") or data.get("exchanges") or data.get("carriers")
        all_results.extend(results)

        total = data["pagination"]["total"]
        offset += limit

        # Avoid rate limits
        if offset < total:
            time.sleep(0.1)

    return all_results

# Usage
all_exchanges = get_all_results(
    "https://api.telco.dev/v1/npa/415",
    os.environ["TELCO_API_KEY"]
)

print(f"Fetched {len(all_exchanges)} exchanges")

Generator Pattern (Memory Efficient)

For very large datasets, use a generator to avoid loading everything into memory:

JavaScript

async function* paginatedResults(baseUrl, apiKey) {
  const limit = 100;
  let offset = 0;
  let total = null;

  while (total === null || offset < total) {
    const url = `${baseUrl}?limit=${limit}&offset=${offset}`;
    const response = await fetch(url, {
      headers: { "X-API-Key": apiKey }
    });

    const data = await response.json();
    const results = data.results || data.exchanges || data.carriers;

    for (const item of results) {
      yield item;
    }

    total = data.pagination.total;
    offset += limit;
  }
}

// Usage
for await (const exchange of paginatedResults(url, apiKey)) {
  console.log(exchange.nxx);
  // Process one at a time
}

Python

def paginated_results(base_url, api_key):
    limit = 100
    offset = 0
    total = None

    while total is None or offset < total:
        response = requests.get(
            base_url,
            params={"limit": limit, "offset": offset},
            headers={"X-API-Key": api_key}
        )
        data = response.json()

        results = data.get("results") or data.get("exchanges") or data.get("carriers")
        for item in results:
            yield item

        total = data["pagination"]["total"]
        offset += limit

# Usage
for exchange in paginated_results(url, api_key):
    print(exchange["nxx"])
    # Process one at a time

Best Practices

1. Use the maximum limit (100) when fetching all data to minimize API calls
2. Check the total field to know when you've fetched everything
3. Add small delays between requests to avoid hitting rate limits
4. Use generators for large datasets to minimize memory usage
5. Cache results if you'll need the same data multiple times
6. Handle errors at each page to avoid losing progress