Health & Stats

Check API health and get database statistics

These public endpoints provide system health information and database statistics. They do not require authentication.

Health Check

Endpoint

GET /v1/health
GET /health

Authentication

None required - This endpoint is public.

Request Example

curl "https://api.telco.dev/v1/health"

Response (200 OK)

{
  "status": "healthy",
  "database": "connected",
  "last_ingestion": "2025-01-15T07:00:00Z",
  "version": "1.0.0"
}

Response Fields

Field	Type	Description
`status`	string	Overall system status: `healthy`, `degraded`, or `unhealthy`
`database`	string	Database connection status: `connected` or `error`
`last_ingestion`	string	ISO 8601 timestamp of last successful data ingestion
`version`	string	API version number

Status Values

Status	Description
`healthy`	All systems operational
`degraded`	Some features may be impacted
`unhealthy`	Critical issues affecting service

Database Statistics

Endpoint

GET /v1/stats
GET /stats

Authentication

None required - This endpoint is public.

Request Example

curl "https://api.telco.dev/v1/stats"

Response (200 OK)

{
  "total_records": 144600,
  "by_country": {
    "US": 99823,
    "CA": 44777
  },
  "by_status": {
    "ASSIGNED": 138450,
    "UNASSIGNED": 4200,
    "RESERVED": 1950
  },
  "last_updated": {
    "NANPA": "2025-01-15T07:00:00Z",
    "CNAC": "2025-01-15T08:00:00Z"
  },
  "coverage": {
    "area_codes": 423,
    "states_provinces": 63
  }
}

Response Fields

Field	Type	Description
`total_records`	integer	Total NPA-NXX records in database
`by_country`	object	Record counts by country code
`by_status`	object	Record counts by assignment status
`last_updated.NANPA`	string	Last US data ingestion time
`last_updated.CNAC`	string	Last Canadian data ingestion time
`coverage.area_codes`	integer	Number of unique area codes
`coverage.states_provinces`	integer	Number of states/provinces covered

Use Cases

Monitoring Integration

Use the health endpoint for uptime monitoring:

async function checkHealth() {
  const response = await fetch("https://api.telco.dev/v1/health");
  const data = await response.json();

  if (data.status !== "healthy") {
    // Send alert
    console.error(`API degraded: ${data.status}`);
  }

  return data.status === "healthy";
}

Display Stats on Your Site

async function getStats() {
  const response = await fetch("https://api.telco.dev/v1/stats");
  return response.json();
}

// Usage
const stats = await getStats();
console.log(`Database contains ${stats.total_records.toLocaleString()} records`);
console.log(`Covering ${stats.coverage.area_codes} area codes`);

Check Data Freshness

async function checkDataFreshness() {
  const stats = await getStats();

  const nanpaDate = new Date(stats.last_updated.NANPA);
  const hoursSinceUpdate = (Date.now() - nanpaDate) / (1000 * 60 * 60);

  if (hoursSinceUpdate > 48) {
    console.warn("US data may be stale");
  }

  return {
    nanpa: stats.last_updated.NANPA,
    cnac: stats.last_updated.CNAC,
    hoursSinceNanpa: Math.round(hoursSinceUpdate)
  };
}