Referencia API

AMRnet proporciona una API completa de RESTful para el acceso programático a todos los datos de vigilancia de resistencia antimicrobiana. La API soporta múltiples formatos de datos, opciones de filtrado y métodos de autenticación para adaptarse a diferentes casos de uso.

Inicio rápido

La API de AMRnet está disponible en https://api.amrnet.org y proporciona acceso a datos de vigilancia para múltiples organismos. Todos los endpoints devuelven JSON por defecto, con capacidades opcionales de exportación CSV.

Uso Básico

# Get all S. Typhi surveillance data
curl "https://api.amrnet.org/styphi"

# Filter by country and year range
curl "https://api.amrnet.org/styphi?country=BGD&year_start=2020&year_end=2023"

# Get summary statistics
curl "https://api.amrnet.org/styphi/summary?country=IND"

Autenticación

La API de AMRnet soporta múltiples métodos de autenticación dependiendo de sus requisitos de uso:

Acceso público

El acceso básico de lectura a todos los conjuntos de datos publicados está disponible sin autenticación. Se aplican los límites:

• Límite de tasas: 1000 solicitudes por hora por IP

• Límite de datos: 10.000 registros por solicitud

• Límite de exportación: 50.000 registros por día

# No authentication required for basic access
curl "https://api.amrnet.org/styphi?limit=1000"

Autenticación de clave API

Para límites de velocidad más altos y acceso a datos a granel, registra una clave API gratuita en amrnet.org/api/register.

# Using API key in header (recommended)
curl -H "X-API-Key: your_api_key_here" "https://api.amrnet.org/styphi"

# Using API key as parameter
curl "https://api.amrnet.org/styphi?api_key=your_api_key_here"

Beneficios de clave API:

• Límite de tarifa: 10.000 solicitudes por hora

• Límite de datos: 100.000 registros por solicitud

• Límite de exportación: 1.000.000 registros por día

• Soporte de prioridad: tiempos de respuesta más rápidos

Autenticación de OAuth2

Para el acceso institucional y características avanzadas, la autenticación de OAuth2 está disponible. Contáctenos en amrnetdashboard@gmail.com para el acceso institucional.

Endpoints disponibles

La API de AMRnet proporciona puntos finales consistentes en todos los órganos soportados con parámetros de consulta estandarizados y formatos de respuesta.

Puntos finales de datos del organismo

Organismos soportados

Organismo	Endpoint	Descripción
Salmonella Typhi	/styphi	Datos de patógeno de fiebre tifoide
Klebsiella pneumoniae	/kpneumo	datos de resistencia pneumoniae
Neisseria gonorrhoeae	/ngono	Datos de patógeno de Gonorrhea
E. coli	/ecoli	patrones de resistencia al coli
E. coli (Diarrheal)	/decoli	cepas diarreicas E. coli
Shigella	/shigella	Datos de especies de Shigella
Salmonella enterica	/senterica	Non-typhoidal Salmonella
S. enterica (Invasiva)	/sentericaints	cepas de salmonela invasivas

Acceso Base de Datos

GET /api/{organism}

Respuesta de ejemplo:

{
    "status": "success",
    "organism": "styphi",
    "total_records": 15420,
    "page": 1,
    "per_page": 100,
    "pages": 155,
    "data": [
        {
            "id": "ERR1234567",
            "country": "Bangladesh",
            "year": 2020,
            "resistance_profile": {
                "ampicillin": "R",
                "chloramphenicol": "S",
                "ciprofloxacin": "I"
            },
            "genotype": "4.3.1.1",
            "collection_date": "2020-03-15",
            "source": "blood",
            "metadata": {
                "age": 25,
                "sex": "F",
                "location": "Dhaka"
            }
        }
    ],
    "filters_applied": {},
    "timestamp": "2024-12-30T10:30:00Z"
}

Estadísticas del resumen

GET /api/{organism}/summary

Respuesta de ejemplo:

{
    "status": "success",
    "organism": "styphi",
    "summary": {
        "total_samples": 15420,
        "countries": 45,
        "year_range": [2010, 2023],
        "resistance_rates": {
            "ampicillin": 0.75,
            "chloramphenicol": 0.23,
            "ciprofloxacin": 0.89
        },
        "genotype_distribution": {
            "4.3.1.1": 0.45,
            "4.3.1.2": 0.32,
            "2.1.7": 0.15
        },
        "geographic_distribution": {
            "Asia": 0.65,
            "Africa": 0.25,
            "Americas": 0.10
        }
    }
}

Datos específicos del país

GET /api/{organism}/countries/{country_code}

Ejemplo:

curl "https://api.amrnet.org/styphi/countries/BGD"

Tendencias temporales

GET /api/{organism}/trends

Respuesta de ejemplo:

{
    "status": "success",
    "trends": {
        "resistance_over_time": [
            {
                "year": 2020,
                "ampicillin_resistance": 0.72,
                "sample_count": 1250
            },
            {
                "year": 2021,
                "ampicillin_resistance": 0.75,
                "sample_count": 1380
            }
        ]
    }
}

Parámetros de consulta

Todos los extremos del organismo soportan parámetros de consulta consistentes para filtrar y personalizar:

Parámetros de filtrado

Filtrar parámetros

Parámetro	Tipo	Descripción
país	cadena	ISO 3166-1 alpha-3 código de país (por ejemplo, BGD, IND, USA)
año_inicio	entero	Año de inicio para filtrado de fecha
fin de año	entero	Fin de año para filtrado de fecha
resistencia	cadena	Filtrar por resistencia al antibiótico específico
genotipo	cadena	Filtrar por genotipo o linaje específico
fuente	cadena	Fuente de ejemplo (sangre, orina, estool, etc.)
región	cadena	Filtro geográfico de región

Parámetros de paginación

Parámetros de paginación

Parámetro	Tipo	Descripción
página	entero	Número de página (por defecto: 1)
por_página	entero	Registros por página (máximo: 10,000)
limit	entero	Límite total de registros
offset	entero	Número de registros a omitir

Parámetros de formato

Parámetros de formato

Parámetro	Tipo	Descripción
formato	cadena	Formato de respuesta: json (por defecto), csv, tsv
campos	cadena	Lista separada por comas de campos a incluir
excluir	cadena	Lista separada por comas de campos a excluir

Ejemplos de consultas

Aquí hay ejemplos prácticos que demuestran patrones de uso comunes de la API:

Filtrado básico

# Get S. Typhi data from Bangladesh in 2020-2023
curl "https://api.amrnet.org/styphi?country=BGD&year_start=2020&year_end=2023"

# Get ciprofloxacin-resistant samples
curl "https://api.amrnet.org/styphi?resistance=ciprofloxacin:R"

# Get specific genotype data
curl "https://api.amrnet.org/styphi?genotype=4.3.1.1"

Filtrado avanzado

# Multiple country filter
curl "https://api.amrnet.org/styphi?country=BGD,IND,PAK"

# Complex resistance pattern
curl "https://api.amrnet.org/styphi?resistance=ampicillin:R,chloramphenicol:S"

# Blood samples from specific region
curl "https://api.amrnet.org/styphi?source=blood&region=South_Asia"

Exportar datos

# Export to CSV
curl "https://api.amrnet.org/styphi?format=csv&limit=50000" > styphi_data.csv

# Export specific fields only
curl "https://api.amrnet.org/styphi?fields=country,year,resistance_profile&format=csv"

# Export with custom filename
curl -o "bangladesh_styphi_2023.csv" \
     "https://api.amrnet.org/styphi?country=BGD&year=2023&format=csv"

Ejemplos de programación

Integración de Python

import requests
import pandas as pd
import json

class AMRnetAPI:
    def __init__(self, api_key=None):
        self.base_url = "https://api.amrnet.org"
        self.session = requests.Session()
        if api_key:
            self.session.headers.update({"X-API-Key": api_key})

    def get_data(self, organism, **filters):
        """Fetch data for specified organism with filters."""
        url = f"{self.base_url}/{organism}"
        response = self.session.get(url, params=filters)
        response.raise_for_status()
        return response.json()

    def get_summary(self, organism, **filters):
        """Get summary statistics for organism."""
        url = f"{self.base_url}/{organism}/summary"
        response = self.session.get(url, params=filters)
        response.raise_for_status()
        return response.json()

    def to_dataframe(self, data):
        """Convert API response to pandas DataFrame."""
        if 'data' in data:
            return pd.DataFrame(data['data'])
        return pd.DataFrame()

# Example usage
api = AMRnetAPI(api_key="your_api_key")

# Get Bangladesh S. Typhi data from 2020-2023
data = api.get_data(
    "styphi",
    country="BGD",
    year_start=2020,
    year_end=2023,
    limit=10000
)

# Convert to DataFrame for analysis
df = api.to_dataframe(data)
print(f"Retrieved {len(df)} samples")

# Get summary statistics
summary = api.get_summary("styphi", country="BGD")
print("Resistance rates:", summary['summary']['resistance_rates'])

R Integración

library(httr)
library(jsonlite)
library(dplyr)

# AMRnet API R client
amrnet_get <- function(organism, ..., api_key = NULL) {
  base_url <- "https://api.amrnet.org"
  url <- paste0(base_url, "/", organism)

  # Prepare headers
  headers <- list()
  if (!is.null(api_key)) {
    headers[["X-API-Key"]] <- api_key
  }

  # Make request
  params <- list(...)
  response <- GET(url, query = params, add_headers(.headers = headers))
  stop_for_status(response)

  # Parse JSON response
  content(response, "parsed", "application/json")
}

# Example usage
data <- amrnet_get("styphi",
                   country = "BGD",
                   year_start = 2020,
                   limit = 5000)

# Convert to data frame
df <- do.call(rbind, lapply(data$data, as.data.frame))
cat("Retrieved", nrow(df), "samples\n")

Integración JavaScript/Node.js

const axios = require('axios');

class AMRnetAPI {
    constructor(apiKey = null) {
        this.baseURL = 'https://api.amrnet.org';
        this.apiKey = apiKey;
    }

    async getData(organism, filters = {}) {
        const url = `${this.baseURL}/${organism}`;
        const headers = this.apiKey ? { 'X-API-Key': this.apiKey } : {};

        try {
            const response = await axios.get(url, {
                params: filters,
                headers: headers
            });
            return response.data;
        } catch (error) {
            throw new Error(`API request failed: ${error.message}`);
        }
    }

    async getSummary(organism, filters = {}) {
        const url = `${this.baseURL}/${organism}/summary`;
        const headers = this.apiKey ? { 'X-API-Key': this.apiKey } : {};

        const response = await axios.get(url, {
            params: filters,
            headers: headers
        });
        return response.data;
    }
}

// Example usage
async function analyzeBangladeshTyphoid() {
    const api = new AMRnetAPI('your_api_key');

    try {
        const data = await api.getData('styphi', {
            country: 'BGD',
            year_start: 2020,
            year_end: 2023,
            limit: 10000
        });

        console.log(`Retrieved ${data.data.length} samples`);

        const summary = await api.getSummary('styphi', { country: 'BGD' });
        console.log('Resistance rates:', summary.summary.resistance_rates);
    } catch (error) {
        console.error('Error:', error.message);
    }
}

analyzeBangladeshTyphoid();

Manejo de errores

La API de AMRnet utiliza códigos de estado estándar HTTP y proporciona mensajes de error detallados para ayudar a diagnosticar problemas:

Código de estado HTTP

Códigos de estado

Código	Descripción
200	Éxito: Solicitud completada con éxito
400	Solicitud incorrecta - Parámetros no válidos o solicitud mal formada
401	No autorizado - Clave API inválida o ausente
403	Prohibida - Se ha superado el límite de acceso denegado o tasa
404	No encontrado - Endpoint o recurso no encontrado
429	Demasiadas solicitudes - Límite de tasa excedido
500	Error interno del servidor - error del lado del servidor

Formato de respuesta de error

{
    "status": "error",
    "error": {
        "code": "INVALID_PARAMETER",
        "message": "Invalid country code 'XX'. Must be valid ISO 3166-1 alpha-3 code.",
        "details": {
            "parameter": "country",
            "value": "XX",
            "valid_values": ["BGD", "IND", "USA", "..."]
        }
    },
    "timestamp": "2024-12-30T10:30:00Z"
}

Escenarios de errores comunes

Código de país no válido:

curl "https://api.amrnet.org/styphi?country=INVALID"
# Returns 400 with list of valid country codes

Límite de tasa excedido:

# Too many requests without API key
# Returns 429 with retry-after header

Solicitud de datos grande:

curl "https://api.amrnet.org/styphi?limit=999999"
# Returns 400 with maximum limit information

Límites de valoración y mejores prácticas

Limitar tasa

AMRnet implementa una limitación de la tasa para garantizar un acceso justo y estabilidad del sistema:

Valorar límites por nivel de acceso

Nivel de acceso	Solicitudes/Hora	Registros/Solicitud	Límite de exportación diario
Público	1,000	10,000	50,000
Clave API	10,000	100,000	1,000,000
Institucional	100,000	1,000,000	Ilimitado

Mejores prácticas

1. Usar claves API para acceso regular:

# Always use API key for applications
headers = {"X-API-Key": "your_api_key"}

2. Implementar el manejo adecuado de errores:

import time
from requests.exceptions import RequestException

def safe_api_call(url, params, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = requests.get(url, params=params)
            if response.status_code == 429:
                # Rate limited - wait and retry
                time.sleep(60)
                continue
            response.raise_for_status()
            return response.json()
        except RequestException as e:
            if attempt == max_retries - 1:
                raise
            time.sleep(2 ** attempt)  # Exponential backoff

3. Usar paginación para conjuntos de datos grandes:

def fetch_all_data(organism, filters):
    all_data = []
    page = 1

    while True:
        response = api.get_data(
            organism,
            page=page,
            per_page=10000,
            **filters
        )

        all_data.extend(response['data'])

        if page >= response['pages']:
            break
        page += 1

    return all_data

4. Resultados de la caché Apriadamente:

import pickle
from datetime import datetime, timedelta

def cached_api_call(cache_file, organism, filters, cache_hours=24):
    # Check if cache exists and is recent
    try:
        with open(cache_file, 'rb') as f:
            cached_data, timestamp = pickle.load(f)

        if datetime.now() - timestamp < timedelta(hours=cache_hours):
            return cached_data
    except FileNotFoundError:
        pass

    # Fetch fresh data
    data = api.get_data(organism, **filters)

    # Cache the result
    with open(cache_file, 'wb') as f:
        pickle.dump((data, datetime.now()), f)

    return data

API de pila FARM

AMRnet está implementando una moderna API de pila FARM (FastAPI + React + MongoDB) para proporcionar un rendimiento mejorado, capacidades en tiempo real y características avanzadas de análisis.

Características de backend FastAPI

Transmisión de datos en tiempo real:

# WebSocket endpoint for real-time updates
from fastapi import FastAPI, WebSocket
import asyncio

app = FastAPI()

@app.websocket("/ws/styphi/live")
async def websocket_endpoint(websocket: WebSocket):
    await websocket.accept()
    while True:
        # Stream real-time resistance trend updates
        data = await get_live_resistance_data()
        await websocket.send_json(data)
        await asyncio.sleep(60)  # Update every minute

Puntos de análisis avanzados:

# Machine learning predictions
curl "https://farm-api.amrnet.org/styphi/predictions/resistance_trends"

# Statistical analysis
curl "https://farm-api.amrnet.org/styphi/statistics/regression_analysis"

# Geospatial clustering
curl "https://farm-api.amrnet.org/styphi/geo/clusters"

Integración GraphQL:

query GetTyphoidData($country: String!, $yearRange: [Int!]!) {
    styphi(filters: {country: $country, years: $yearRange}) {
        samples {
            id
            resistanceProfile {
                ampicillin
                ciprofloxacin
                ceftriaxone
            }
            genotype
            location {
                country
                coordinates
            }
        }
        summary {
            totalSamples
            resistanceRates
            temporalTrends
        }
    }
}

Componentes React Frontend

Explorador Interactivo de API:

import React, { useState } from 'react';
import { APIExplorer } from '@amrnet/react-components';

function APIPlayground() {
    const [organism, setOrganism] = useState('styphi');
    const [filters, setFilters] = useState({});

    return (
        <APIExplorer
            organism={organism}
            filters={filters}
            onFiltersChange={setFilters}
            showCodeExamples={true}
            allowExport={true}
        />
    );
}

Widgets de panel de tiempo real:

import { LiveResistanceChart } from '@amrnet/react-components';

function LiveDashboard() {
    return (
        <div>
            <LiveResistanceChart
                organism="styphi"
                country="BGD"
                updateInterval={60000}  // 1 minute
            />
        </div>
    );
}

Consultas avanzadas de MongoDB

Análisis de series temporales:

// MongoDB aggregation for temporal trends
db.styphi.aggregate([
    {
        $match: {
            country: "BGD",
            year: { $gte: 2020 }
        }
    },
    {
        $group: {
            _id: {
                year: "$year",
                month: "$month"
            },
            resistance_rate: {
                $avg: {
                    $cond: [
                        { $eq: ["$resistance.ciprofloxacin", "R"] },
                        1, 0
                    ]
                }
            },
            sample_count: { $sum: 1 }
        }
    },
    {
        $sort: { "_id.year": 1, "_id.month": 1 }
    }
])

Análisis geoespacial:

// Find samples within geographic radius
db.styphi.find({
    location: {
        $geoWithin: {
            $centerSphere: [
                [90.4125, 23.8103],  // Dhaka coordinates
                50 / 3963.2  // 50 miles radius
            ]
        }
    }
})

Soporte y Recursos

Obtén ayuda y conéctate con la comunidad de desarrolladores de AMRnet:

Recursos de documentación

• 📖 Guía de usuario: Instrucciones de uso completas del panel de control

• 🛠️ Guía de desarrollador: Contribuyendo y añadiendo nuevos órganos.

• 📊 Diccionario de Datos: Completa definiciones de campos y esquemas

• 🎓 Tutoriales: Ejemplos de integración paso a paso

Soporte de la comunidad

• :speech _balloon: Discusiones de GitHub: github.com/amrnet/amrnet/discussions

• 🐛 Issue Tracker: github.com/amrnet/amrnet/issues

• 📧 Soporte por email: amrnetdashboard@gmail.com

• 📋 API Status: status.amrnet.org

Servicios profesionales

Para organizaciones que requieren soporte de integración personalizada, capacitación o características de la empresa:

• 🏢 Acceso a la API de la empresa: Límites de tasa más altos y garantías de SLA

• 🎓 Talleres de formación: integración de API y análisis de datos AMR

• 🔧 Desarrollo a medida: Soluciones cubiertas e implementaciones privadas

• 📊 Servicios de consulta: estrategia e implementación de vigilancia de AMR

Póngase en contacto con nuestro equipo empresarial en amrnetdashboard@gmail.com para más información.

Cambios y versiones

La API de AMRnet sigue la versión semántica. Los cambios en la versión mayor pueden incluir cambios de ruptura, mientras que las versiones menores añaden características con compatibilidad con versiones anteriores.

Versión actual: v2.1.0

Nuevas características: - Implementación de pila FARM con backend FastAPI - endpoints WebSocket en tiempo real para streaming de datos en vivo - Soporte API GraphQL para consultas flexibles - Capacidades de análisis geoespacial mejoradas - endpoints de predicción de aprendizaje automático

Mejoras: - 40% más rápido de los tiempos de respuesta con procesamiento asíncrono - Mejores mensajes de error con diagnósticos detallados - Límite de velocidad mejorada con capacidad de ráfagas - Mejor caché para datos de acceso frecuente

Correcciones de errores: - Solucionado problemas de paginación con grandes conjuntos de datos - Resuelto manejo de zonas de tiempo en filtros de fecha - Corregidos cálculos de tasa de resistencia para genotipos específicos

Historial de versiones

• v2.1.0 (2024-12-30): implementación de pila FARM, características en tiempo real

• v2.0.0 (2024-06-15): Rediseño de la API principal con puntos finales consistentes

• v1.5.2 (2024-03-10): Capacidades de filtrado y exportación mejoradas

• v1.5.0 (2024-01-20): Se añadieron puntos finales de estadísticas de resumen

• v1.4.1 (2023-11-05): Mejoras de rendimiento y correcciones de errores

• v1.4.0 (2023-09-15): soporte de autenticación OAuth2

• v1.3.0 (2023-07-01): Sistema de autenticación de claves API

• v1.2.0 (2023-04-10): funcionalidad de exportación CSV

• v1.1.0 (2023-02-01): Paginación y filtrado avanzado

• v1.0.0 (2023-01-01): Versión pública inicial de la API

Guía de Migración

Migración de v1.x a v2.x:

# v1.x (deprecated)
response = requests.get("https://api.amrnet.org/data/styphi")

# v2.x (current)
response = requests.get("https://api.amrnet.org/styphi")

Cambios de ruptura en v2. : - Estructura de punto final simplificada (/data/{organism} → /{organism}) - Formato de respuesta estandarizado en todos los extremos - El filtro de fechas utiliza year_start/year_end en lugar de date_from/date_to - Valores de resistencia estandarizados (R/I/S en lugar de códigos numéricos)

Aviso de Deprecación

Advertencia

los endpoints de la API v1.x serán obsoletos el 30 de junio de 2025. Por favor migra a los endpoints v2.x antes de esta fecha. Los puntos finales antiguos seguirán funcionando hasta el 31 de diciembre de 2025, después de lo cual serán eliminados permanentemente.