Référence API¶

AMRnet fournit une API complète RESTful pour un accès programmatique à toutes les données de surveillance de résistance aux antimicrobiens. L’API prend en charge plusieurs formats de données, des options de filtrage et des méthodes d’authentification qui conviennent à différents cas d’utilisation.

Démarrage rapide¶

L’API AMRnet est disponible sur https://api.amrnet.org et fournit un accès aux données de surveillance pour plusieurs organismes. Tous les terminaux retournent JSON par défaut, avec des capacités d’exportation CSV optionnelles.

Utilisation de base¶

# 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"

Authentification¶

L’API AMRnet prend en charge plusieurs méthodes d’authentification en fonction de vos besoins d’utilisation :

Accès public¶

L’accès en lecture de base à tous les jeux de données publiés est disponible sans authentification. Les limites de taux s’appliquent :

Limite de tarification: 1000 demandes par heure par IP
Limite de données : 10 000 enregistrements par requête
Limite d’exportation: 50 000 enregistrements par jour

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

Authentification de la clé API¶

Pour obtenir des limites de taux plus élevées et un accès groupé aux données, inscrivez-vous pour obtenir une clé API gratuite à 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"

Avantages clés de l’API:

Limite de tarification: 10 000 demandes par heure
Limite de données : 100 000 enregistrements par requête
Limite d’exportation : 1 000 000 enregistrements par jour
Support prioritaire : temps de réponse plus rapide

Authentification OAuth2¶

Pour un accès institutionnel et des fonctionnalités avancées, l’authentification OAuth2 est disponible. Contactez-nous à amrnetdashboard@gmail.com pour un accès institutionnel.

Points de terminaison disponibles¶

L’API AMRnet fournit des terminaux cohérents à tous les organismes pris en charge avec des paramètres de requête normalisés et des formats de réponse.

Points de terminaison des données de l’organisme¶

Organismes pris en charge¶
Organisme	Endpoint	Libellé
Salmonella Typhi	`/styphi`	Données pathogènes de la fièvre typhoïde
Klebsiella pneumoniae	`/kpneumo`	données de résistance pneumoniae
Neisseria gonorrhoeae	`/ngono`	Données pathogènes de la gonorrhée
E. coli	`/ecoli`	motifs de résistance au coli
E. coli (Diarrheal)	`/decoli`	déformations de Diarrheal E. coli
Shigella	`/shigella`	Données sur les espèces de Shigella
Salmonella entérique	`/senterica`	Non-typhoidal Salmonella
S. enterica (invasive)	`/sentericaints`	Souches invasives de salmonelle

Accès aux données de base¶

GET /api/{organism}

Exemple de Réponse :

{
    "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"
}

Statistiques sommaires¶

GET /api/{organism}/summary

Exemple de Réponse :

{
    "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
        }
    }
}

Données spécifiques à un pays¶

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

Exemple :

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

Tendances temporelles¶

GET /api/{organism}/trends

Exemple de Réponse :

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

Paramètres de requête¶

Tous les terminaux de l’organisme supportent des paramètres de requête cohérents pour le filtrage et la personnalisation :

Paramètres de filtrage¶

Paramètres de filtre¶
Paramètre	Type de texte	Libellé
`country`	chaîne de caractères	Code pays ISO 3166-1 alpha-3 (par exemple, BGD, IND, USA)
`year_start`	entier	Année de début pour le filtrage de la plage de dates
`year_end`	entier	Fin de l’année pour le filtrage de la plage de dates
`resistance`	chaîne de caractères	Filtrer par résistance à un antibiotique spécifique
“génotype”	chaîne de caractères	Filtrer par génotype ou ligne spécifique
`source`	chaîne de caractères	Source d’échantillon (sang, urine, sel, etc.)
`region`	chaîne de caractères	Filtre de région géographique

Paramètres de pagination¶

Paramètres de pagination¶
Paramètre	Type de texte	Libellé
`page`	entier	Numéro de page (par défaut: 1)
`per_page`	entier	Enregistrements par page (max : 10 000)
`limit`	entier	Limite totale de l’enregistrement
`offset`	entier	Nombre d’enregistrements à ignorer

Paramètres de format¶

Paramètres de format¶
Paramètre	Type de texte	Libellé
`format`	chaîne de caractères	Format de réponse : json (par défaut), csv, tsv
`fields`	chaîne de caractères	Liste de champs séparés par des virgules à inclure
`exclude`	chaîne de caractères	Liste de champs séparés par des virgules à exclure

Exemples de requêtes¶

Voici des exemples pratiques démontrant des modèles d’utilisation courants de l’API :

Filtrage de base¶

# 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"

Filtrage avancé¶

# 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"

Export des données¶

# 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"

Exemples de programmation¶

Intégration 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'])

Intégration R¶

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")

Intégration de 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();

Gestion des erreurs¶

L’API AMRnet utilise des codes d’état HTTP standard et fournit des messages d’erreur détaillés pour aider à diagnostiquer les problèmes :

Codes d’état HTTP¶

Codes de statut¶
Code	Libellé
`200`	Succès - Demande terminée avec succès
`400`	Requête incorrecte - Paramètres invalides ou requête mal formée
`401`	Non autorisé - Clé API invalide ou manquante
`403`	Interdit - Accès refusé ou limite de taux dépassée
`404`	Pas trouvé - Point d’extrémité ou ressource introuvable
`429`	Trop de requêtes - Limite de taux dépassée
`500`	Erreur interne du serveur - Erreur côté serveur

Format de réponse d’erreur¶

{
    "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"
}

Scénarios d’erreurs communs¶

Code de pays invalide:

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

Limite de taux dépassée :

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

Grande demande de données :

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

Limites de taux et meilleures pratiques¶

Limitation des taux¶

AMRnet implémente une limitation de débit pour assurer un accès équitable et la stabilité du système :

Limites de taux par niveau d’accès¶
Niveau d’accès	Demandes / Heure	Enregistrements/Requête	Limite d’exportation quotidienne
Publique	1,000	10,000	50,000
Clé API	10,000	100,000	1,000,000
Institutionnel	100,000	1,000,000	Illimité

Meilleures pratiques¶

1. Utilisez les clés API pour un accès régulier:

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

2. Implémenter une gestion adéquate des erreurs :

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. Utiliser la pagination pour les grands jeux de données:

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. Résultats de la cache correctement :

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 la pile FARM¶

AMRnet implémente une API de pile moderne FARM (FastAPI + React + MongoDB) pour fournir des performances améliorées, des capacités en temps réel et des fonctionnalités d’analyse avancées.

Fonctionnalités d’administration de FastAPI¶

Streaming de données en temps réel :

# 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

Points de terminaison Analytiques avancés:

# 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"

Intégration 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
        }
    }
}

Composants React Frontend¶

Explorateur interactif de l’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 tableau de bord en temps réel :

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

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

Requêtes avancées MongoDB¶

Analyses de la série temporelle :

// 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 }
    }
])

Analyse géospatiale :

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

Support et ressources¶

Obtenir de l’aide et se connecter avec la communauté de développeurs AMRnet :

Ressources de la documentation¶

📖 Guide d’utilisation: Instructions d’utilisation du tableau de bord complet
🛠️ Developer Guide: Contribuer et ajouter de nouveaux organismes
📊 Dictionnaire de données: Définitions de champs et schémas complets
🎓 Tutoriels: Exemples d’intégration étape par étape

Support de la communauté¶

💬 Discussions GitHub: github.com/amrnet/amrnet/discussions
🐛 Suivi de problèmes: github.com/amrnet/amrnet/issues
📧 Support par e-mail: amrnetdashboard@gmail.com
📋 API Status: status.amrnet.org

Services professionnels¶

Pour les organisations nécessitant un support d’intégration personnalisé, une formation ou des fonctionnalités d’entreprise :

🏢 Enterprise API Access: Des limites de taux plus élevées et des garanties de SLA
🎓 Ateliers de formation: Intégration API et analyse des données AMR
🔧 Développement personnalisé: Solutions sur mesure et déploiements privés
📊 Services de consultation: Stratégie de surveillance AMR et implémentation

Contactez notre équipe d’entreprise à amrnetdashboard@gmail.com pour plus d’informations.

Changelog et Versioning¶

L’API AMRnet suit les versions sémantiques. Les changements majeurs de version peuvent inclure des changements de rupture, tandis que les versions mineures ajoutent des fonctionnalités avec la compatibilité ascendante.

Version actuelle : v2.1.0¶

Nouvelles fonctionnalités : - Implémentation de piles FARM avec le backend FastAPI - Points de terminaison WebSocket en temps réel pour le streaming de données en temps réel - Prise en charge de l’API GraphQL pour les requêtes flexibles - Fonctionnalités avancées d’analyse géospatiale - Terminaux d’apprentissage automatique de la prédiction

Améliorations: - 40% de temps de réponse plus rapides avec un traitement asynchrone - Messages d’erreur améliorés avec des diagnostics détaillés - Taux de limitation amélioré avec capacité d’éclatement - Meilleure mise en cache pour les données fréquemment consultées

Corrections de bugs : - Problèmes de pagination résolus avec de grands jeux de données - Gestion résolue des fuseaux horaires dans les filtres de dates - Calcul de la résistance pour les génotypes spécifiques

Historique des versions¶

v2.1.0 (2024-12-30): implémentation de piles FARM, fonctionnalités en temps réel
v2.0.0 (2024-06-15): Reconception majeure de l’API avec des points de terminaison cohérents
v1.5.2 (2024-03-10): Amélioration des capacités de filtrage et d’exportation
v1.5.0 (2024-01-20): Fin des statistiques ajoutées
v1.4.1 (2023-11-05) : Améliorations des performances et corrections de bugs
v1.4.0 (2023-09-15): Support de l’authentification OAuth2
v1.3.0 (2023-07-01) : Système d’authentification des clés API
v1.2.0 (2023-04-10): Fonction d’exportation CSV
v1.1.0 (2023-02-01) : Pagination et filtrage avancé
v1.0.0 (2023-01-01) : Version initiale de l’API publique

Tutoriels de migration¶

Migration de v1.x vers 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")

Casser les changements dans v2. : - Structure d’extrémité simplifiée (/data/{organism} → /{organism}) - Format de réponse standardisé sur tous les terminaux - Le filtrage de date utilise year_start/year_end au lieu de date_from/date_to - Valeurs de résistance normalisées (R/I/S au lieu de codes numériques)

Avis de dépréciation¶

Avertissement

Les points de terminaison de l’API v1.x seront obsolètes le 30 juin 2025. Veuillez migrer vers les points de terminaison v2.x avant cette date. Les anciens terminaux continueront de fonctionner jusqu’au 31 décembre 2025, après quoi ils seront supprimés définitivement.