Referência de API¶

O AMRnet fornece uma API RESTful abrangente para acesso programático a todos os dados de vigilância da resistência antimicrobiana. A API suporta vários formatos de dados, opções de filtragem e métodos de autenticação para atender a diferentes casos de uso.

Início rápido¶

A API AMRnet está disponível no https://api.amrnet.org e fornece acesso aos dados de vigilância para vários organismos. Todos os endpoints retornam JSON por padrão, com capacidades opcionais de exportação de CSV para 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"

Autenticação¶

A API AMRnet suporta múltiplos métodos de autenticação, dependendo dos seus requisitos de uso:

Acesso Público¶

Acesso de leitura básico a todos os datasets publicados está disponível sem autenticação. Limites de taxa aplicados:

Limite de taxa: 1000 pedidos por hora por IP
Limite de dados: 10.000 registros por pedido
Limite de exportação: 50.000 registros por dia

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

Autenticação de Chave API¶

Para maiores limites de taxa e acesso em massa de dados, registre-se para uma chave de API gratuita em 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"

Benefícios chave da API:

Limite de taxa: 10.000 pedidos por hora
Limite de dados: 100.000 registros por pedido
Limite de exportação: 1,000.000 registros por dia
Suporte prioridade: tempos de resposta mais rápidos

Autenticação OAuth2¶

Para acesso institucional e recursos avançados, a autenticação OAuth2 está disponível. Contate-nos em amrnetdashboard@gmail.com para acesso institucional.

Pontos finais disponíveis¶

A API AMRnet fornece endpoints consistentes em todos os organismos suportados com parâmetros de consulta padronizados e formatos de resposta.

Fim dos Dados do Organismo¶

Organismos Suportados¶
Organismo	Endpoint	Descrição:
Salmonella Typhi	`/styphi`	Dados patogênicos da febre Typhoid
Klebsiella pneumoniae	`/kpneumo`	Dados de resistência pneumoniae
Neisseria gonorrhoeae	`/ngono`	Dados patogênicos da Gonorrhea
E. colibo	`/ecoli`	padrões de resistência a coli
E. coli (Diarrheal)	`/decoli`	Diarreia E. coli strains
Shigella	`/shigella`	Dados da espécie Shigella
Consulta de Salmonela	`/senterica`	Non-typhoidal Salmonella
S. enterica (Invasive)	`/sentericaints`	Habilidades Invasivas de Salmonela

Acesso Base aos Dados¶

GET /api/{organism}

Resposta de exemplo:

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

Estatísticas Resumidas¶

GET /api/{organism}/summary

Resposta de exemplo:

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

Dados específicos do País¶

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

Exemplo:

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

Tendências temporais¶

GET /api/{organism}/trends

Resposta de exemplo:

{
    "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 da consulta¶

Todos os pontos de extremidade de organismos suportam parâmetros consistentes de consulta para filtragem e personalização:

Parâmetros de Filtragem¶

Parâmetros do Filtro¶
Parâmatro	tipo	Descrição:
`país`	sequência	Código de país ISO 3166-1 alpha-3 (por exemplo, BGD, IND, EUA)
`ano_começo_ano`	inteiro	Ano inicial para filtragem do intervalo de datas
`ano_fim`	inteiro	Fim do ano para filtragem do intervalo de datas
`resistência`	sequência	Filtrar por resistência a antibióticos específicos
`genotipo`	sequência	Filtrar por genótipo específico ou linhagem
`origem`	sequência	Exemplo de fonte (sangue, urine, stool, etc.)
`região`	sequência	Filtro de região geográfica

Parâmetros de paginação¶

Parâmetros de paginação¶
Parâmatro	tipo	Descrição:
`página`	inteiro	Número da página (padrão: 1)
`per_page`	inteiro	Registros por página (máx: 10.000)
`limit`	inteiro	Limite total de registros
`offset`	inteiro	Número de registros a ignorar

Parâmetros de formato¶

Parâmetros de formato¶
Parâmatro	tipo	Descrição:
`formato`	sequência	Formato de resposta: json (padrão), csv, tsv
`fields`	sequência	Lista de campos a incluir separados por vírgula
`exclude`	sequência	Lista de campos separados por vírgula para excluir

Exemplo de consultas¶

Aqui estão exemplos práticos que demonstram padrões comuns de uso da API:

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

Filtro Avançado¶

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

Exportação de Dados¶

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

Exemplos de programação¶

Integração 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'])

Integração 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")

Integração 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();

Tratamento de erros¶

A API AMRnet usa códigos de status HTTP padrão e fornece mensagens de erro detalhadas para ajudar a diagnosticar problemas:

Códigos de Status HTTP¶

Códigos de Status¶
Código	Descrição:
`200`	Solicitação concluída com sucesso
`400`	Requisição inválida - parâmetros inválidos ou solicitação mal formada
`401`	Não autorizado - Chave de API inválida ou ausente
`403`	Proibido - acesso negado ou limite de taxa excedido
`404`	Não encontrado - Endpoint ou recurso não encontrado
`429`	Muitas Solicitações - Limite de Taxa excedido
`500`	Erro interno do servidor - erro do servidor

Formato de resposta de erro¶

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

Cenários de erro comuns¶

Código inválido:

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

Limite de Taxa Excedido:

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

Pedidos de dados grandes:

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

Taxa Limites e melhores práticas¶

Taxa Limitada¶

O AMRnet implementa o limite da taxa para garantir acesso justo e estabilidade do sistema:

Limites de Taxa por Nível de Acesso¶
Nível de Acesso	Pedidos/Hora	Registros/Solicitar	Limite Diário de Exportação
Público	1,000	10,000	50,000
Chave de API	10,000	100,000	1,000,000
Instituição	100,000	1,000,000	Ilimitado

Práticas recomendadas¶

1. Use chaves de API para acesso regular:

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

2. Implementação da Proporção de Erro de Manipulação:

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. Use a paginação para grandes datasets:

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 do cache apropriados:

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 FARM Stack¶

O AMRnet está implementando uma API moderna FARM (FastAPI + React + MongoDB) para fornecer desempenho aprimorado, capacidades em tempo real e recursos avançados de análise.

Funcionalidades do Backend FastAPI¶

Transmissão de dados em tempo 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

Pontos de Análise Avançados:

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

Integração com 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 de Frontend React¶

Explorador de API interativo:

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 do Painel em tempo real:

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

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

Consultas Avançadas do MongoDB¶

Análises de Tempo:

// 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álise geoespacial:

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

Suporte e recursos¶

Obtenha ajuda e conecte-se com a comunidade de desenvolvedor AMRnet:

Recursos de Documentação¶

📖 Guia do usuário: Instruções gerais de uso do painel
🛠️ Guia de Desenvolvedor: Contribuindo e adicionando novos organismos
📊 Dicionário de Dados: definições de campo completas e esquemas
🎓 Tutoriais: Exemplos de integração passo a passo

Apoio da Comunidade¶

💬 GitHub Discussions: github.com/amrnet/amrnet/discussions
🐛 Issue Tracker: github.com/amrnet/amrnet/issues
📧 Suporte por e-mail: amrnetdashboard@gmail.com
📋 API Status: status.amrnet.org

Serviços Profissionais¶

Para organizações que exigem suporte de integração personalizada, treinamento ou recursos empresariais:

🏢 Acesso à API da Enterprise: Limites de taxa mais altos e garantias de SLA
🎓 Workshops de treinamento: integração de API e análise de dados AMR
🔧 Desenvolvimento personalizado: soluções personalizadas e implantações privadas
📊 Serviços de consulta: estratégia de vigilância e implementação da RAM

Entre em contato com a nossa equipe corporativa em amrnetdashboard@gmail.com para mais informações.

Mudanças e Versionamento¶

A API AMRnet segue o versionamento semântico. Alterações na versão principais podem incluir alterações na falha, enquanto versões menores adicionam recursos com compatibilidade com versões anteriores.

Versão atual: v2.1.0¶

Novos Recursos: - Implementação FARM stack com o backend FastAPI - endpoints de WebSocket em tempo real para streaming de dados ao vivo - API GraphQL para consultas flexíveis - Recursos de análise geoespacial melhorados - Pontos de previsão do aprendizado automático

Melhorias: - 40% mais rápido de resposta com processamento assíncrono - Mensagens de erro melhoradas com diagnósticos detalhados - Limite de velocidade aumentada com capacidade de estouramento - Melhor cache para dados acessados com frequência

Correções de bugs: - Problemas de paginação corrigidos com grandes conjuntos de dados - Manutenção de fuso horário resolvido nos filtros de data - Cálculos de taxa de resistência fixa para genótipos específicos

Histórico de Versão¶

v2.1.0 (2024-12-30): Implementação da pilha FARM, recursos em tempo real
v2.0.0 (2024-06-15): Redesign de API principal com endpoints consistentes
v1.5.2 (2024-03-10): Filtragem e recursos de exportação aprimorados
v1.5.0 (2024-01-20): Adicionado resumos de estatísticas
v1.4.1 (2023-11-05): Melhorias de desempenho e correções de bugs
v1.4.0 (2023-09-15): suporte a autenticação OAuth2
v1.3.0 (2023-07-01): sistema de autenticação de chave de API
v1.2.0 (2023-04-10): funcionalidade de exportação CSV
v1.1.0 (2023-02-01): Paginação e filtragem avançada
v1.0.0 (2023-01-01): Versão inicial da API pública

Guias de migração¶

Migrando da v1.x para 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")

Quebrando mudanças na v2. : Estrutura de Endpoint simplificada (/data/{organism} → /{organism}) - Formato de resposta padronizado em todos os endpoints - filtragem de datas usa year_start/year_end em vez de date_from/date_to - Valores de resistência padronizados (R/I/S em vez de códigos numéricos)

Aviso de desaprovação¶

Aviso

v1.x endpoints de API serão descontinuados em 30 de junho de 2025. Por favor, migre para a v2.x pontos de extremidade antes desta data. Os endpoints legados continuarão a funcionar até 31 de Dezembro de 2025, após o que serão permanentemente removidos.