Live Italy API wrapper — Fetch Italian statistics across economy, population, health, politics, society, security, work, and media. Full TypeScript support included.
Base URL: https://live-italy.vercel.app/api
- Unified data model (single
statisticstable) - Language output: Italian or English via
?lang=it|en - Pagination & sorting included
npm i live-italyFull TypeScript types and IntelliSense are included.
// ES Module
import { getStatistics, getCategories, getMetrics, getHealth, type StatisticsResponse } from 'live-italy';
const res: StatisticsResponse = await getStatistics({ category: 'economy', lang: 'en', format: 'compact' });
console.log(res.data);// CommonJS
const { getStatistics, getCategories, getMetrics, getHealth } = require('live-italy');
(async () => {
const health = await getHealth();
console.log(health.status);
})();The getStatistics() method retrieves values directly from the statistics table, exactly as stored. It supports filtering, pagination, sorting, and output translation.
const { getStatistics } = require('live-italy');
async function main() {
try {
// Economy (English), compact output
const economyCompact = await getStatistics({
category: 'economy',
lang: 'en',
format: 'compact'
});
console.log('Economy (compact):', economyCompact.data);
// Single metric (GDP), full output with ordering
const gdpFull = await getStatistics({
metric: 'gdp',
lang: 'en',
sort: 'updated_at',
order: 'desc',
limit: 50
});
console.log('GDP (full):', gdpFull.data);
// Pagination example
const page2 = await getStatistics({ offset: 100, limit: 50 });
console.log('Page 2 size:', page2.data.length);
} catch (err) {
console.error('Statistics error:', err.message);
}
}
main();type Lang = 'it' | 'en';
type SortField = 'category' | 'metric' | 'value' | 'updated_at' | 'last_updated';
type SortOrder = 'asc' | 'desc';
type Format = 'full' | 'compact';category— (optional) Filter by category (IT or EN), e.g."economia"/"economy"metric— (optional) Filter by metric (IT or EN), e.g."pil"/"gdp"lang— (optional)"it"|"en"; default"it"(translates output labels only)limit— (optional) default100, max1000offset— (optional) default0sort— (optional)"category" | "metric" | "value" | "updated_at" | "last_updated"(default"updated_at")order— (optional)"asc"|"desc"(default"desc")format— (optional)"full"|"compact"(default"full")
The getCategories() method returns available categories in the selected language.
const { getCategories } = require('live-italy');
(async () => {
const it = await getCategories(); // default 'it'
const en = await getCategories({ lang: 'en' });
console.log('IT categories:', it.data);
console.log('EN categories:', en.data);
})();lang— (optional)"it"|"en"; default"it"
Example Response
{
"success": true,
"data": ["population", "economy", "society", "work", "media", "politics", "security", "health"],
"total_categories": 8,
"filters_applied": { "language": "en" }
}The getMetrics() method lists metrics, optionally filtered by category, and translated according to lang.
const { getMetrics } = require('live-italy');
async function list() {
// All metrics (IT)
const all = await getMetrics();
// Metrics for economy (EN)
const economy = await getMetrics({ category: 'economy', lang: 'en' });
console.log('All (IT):', all.data.length, 'blocks');
console.log('Economy (EN):', economy.data[0]);
}
list();category— (optional) Filter by category (IT or EN)lang— (optional)"it"|"en"; default"it"
Example Response
{
"success": true,
"data": [
{ "category": "economy", "metrics": ["gdp", "public_debt", "debt_interest", "tax_evasion", "wealthy", "poor"] },
{ "category": "population", "metrics": ["total", "births_per_year", "deaths_per_year", "immigrants_per_year", "emigrants_per_year", "total_immigrants", "births_today", "deaths_today", "current_population"] }
],
"total_categories": 8,
"filters_applied": { "category": null, "language": "en" }
}The getHealth() method retrieves a simple API and database status snapshot.
const { getHealth } = require('live-italy');
(async () => {
const health = await getHealth();
console.log(health.status, health.database?.status);
})();Example Response
{
"status": "healthy",
"api_version": "2.0.0",
"timestamp": "2025-10-26T00:00:00.000Z",
"database": {
"status": "connected",
"server_time": "2025-10-26T00:00:00.000Z",
"total_statistics": 65
},
"endpoints": ["/api/statistics", "/api/categories", "/api/metrics", "/api/health"]
}All methods throw an Error on failure. Use try/catch:
try {
const stats = await getStatistics({ metric: 'gdp', lang: 'en' });
console.log(stats.data);
} catch (error) {
console.error('Request failed:', error.message);
}The SDK translates output labels based on ?lang=it|en.
Examples:
Categories
| Italian | English |
|---|---|
| popolazione | population |
| economia | economy |
| societa | society |
| lavoro | work |
| media | media |
| politica | politics |
| sicurezza | security |
| salute | health |