API AGX v1 – Reference rapida

Descrive esattamente cosa restituiscono https://api.agx.sh e gli endpoint /v1/info e /v1/prices.

Questi appunti descrivono lo stato attuale della versione pubblica. Controlla sempre api.agx.sh per verificare se sono state aggiunte nuove versioni o campi.

Copertura attuale

La v1 espone i listini della Borsa Merci di Verona (VR) con dati settimanali comprensivi di high/low. Non sono integrati altri exchange.

Metadati generali (GET https://api.agx.sh)

La root dell'API espone informazioni statiche in formato testo:

AGX API
Base URL: https://api.agx.sh

Available versions:
• v1 - https://api.agx.sh/v1

For detailed documentation, visit each version endpoint.

Usalo per:

  • Verificare la reachability: se ricevi questo payload significa che l'edge è raggiungibile e che puoi proseguire verso gli endpoint versionati.
  • Elencare versioni supportate: puoi mostrare le versioni disponibili all'interno della tua piattaforma o CLI.

/v1/info – indice completo dei prodotti

GET https://api.agx.sh/v1/info restituisce l'elenco dei prodotti attivi, raggruppati per exchange. È la base dati da cui leggere simboli, categorie e unità di misura prima di effettuare interrogazioni storiche.

AGX API v1
Base URL: https://api.agx.sh/v1

Available Endpoints:

─────────────────────────────────────────────────────────────────

INFO - Complete list of traded commodities

GET /v1/info 
Rate limit: 5/minute

Parameters: None

Response:
{
  "exchanges": [
    {
      "exchange": <string>,
      "products": [
        {
          "symbol": <string>,
          "name": <string>,
          "category": <string>,
          "units": <string>,
          "info": <string>,
          "last_date": <date>,
          "change_pct": <float>
        }
      ]
    }
  ]
}

Campi principali

  • exchange: identificatore della piazza o del fornitore (oggi solo "VR").
  • products[]: elenco dei prodotti legati a quell'exchange.
    • symbol: codice necessario per interrogare /v1/prices.
    • category: utile per organizzare i listini in gruppi (Power, Gas, Cereali…).
    • units: unità di misura del prezzo (es. "euro/ton"), mostrala vicino ai numeri per evitare ambiguità.
    • info: descrizione leggibile, mostrala nelle UI o documentazione interna.
    • last_date / change_pct: fotografia sintetica dell'ultimo aggiornamento.

Suggerimenti operativi

  1. Aggiorna il catalogo quando serve – rileggi /v1/info per acquisire nuovi simboli quando vengono aggiunti alla piazza VR.
  2. Mapping centralizzato – memorizza symbol e exchange in modo da poter lanciare interrogazioni storiche senza hardcodare coppie in codice.

/v1/prices – serie storiche

GET https://api.agx.sh/v1/prices espone i prezzi storici del prodotto selezionato con frequenza settimanale.

PRICES - Historical commodity prices

GET /v1/prices

Parameters:
• symbol   <string>  Product symbol (required)
• exchange <string>  Exchange code (required)
• start    <date>    Start date (yyyy-mm-dd) (required)
• end      <date>    End date (yyyy-mm-dd) (required)

Response:
{
  "exchange": <string>,
  "product": <string>,
  "symbol": <string>,
  "units": <string>,
  "timeframe": <string>,
  "data": [
    {
      "timestamp": <date>,
      "high": <float>,
      "low": <float>
    }
  ]
}

Come usarlo in produzione

  • Validazione parametri – rifiuta richieste senza symbol e exchange; la risposta non include fallback se mancano.
  • Frequenza dati – timeframe indica l'aggregazione (per VR è settimanale). Mostralo per evitare ambiguità.
  • Aggregazioni – calcola derivate (medie, scostamenti) lato tuo applicativo partendo dai valori high e low restituiti.

Collegamenti utili