API dei dati

L’API si aprirà quando la sua banca dati sarà attiva. Le chiavi non vengono ancora rilasciate.

Stato

L’API non fornisce ancora dati. Finché non si apre, una richiesta viene rifiutata, non vengono rilasciate chiavi e non si può contare sul funzionamento di nulla di quanto descritto in questa pagina. Questa pagina descrive ciò che sarà offerto.

Che cos’è

Un endpoint per ogni confronto (mobile, internet, tv, phone). Restituisce le offerte che meconomy.ch mostra con prova conservata, ciascuna con la sua fonte e il lettore indicato in evidence.reader: parser (MEconomyBot, dalla pagina del fornitore), official (una fonte ufficiale) o human (una persona in una consultazione assistita).

Non inclusi: i prezzi che aggiorniamo a mano, gli altri confronti, il testo del fornitore e i file di prova conservati. Dove una cifra non è indicata, il campo è null, che significa «non indicato», non «nessuno».

Ottenere una chiave

La richieda tramite la pagina di contatto con l’argomento «Chiave API», indicando l’organizzazione o il progetto e lo scopo. Le chiavi sono gratuite e rilasciate da MEconomy. Viene rilasciata una chiave per organizzazione o progetto.

Tenga segreta la chiave e la conservi su un server. Le richieste da una pagina del browser non sono supportate: l’API non invia intestazioni CORS e una chiave nel codice di una pagina è visibile a chiunque apra la pagina.

Richiesta

Invii una richiesta GET con la chiave nell’intestazione Authorization. L’unico parametro è provider, facoltativo, uno slug del fornitore. Una chiave nell’indirizzo viene rifiutata.

curl -H "Authorization: Bearer mek_your-key" \
  "https://meconomy.ch/api/v1/mobile/offers?provider=example"

Risposta

La struttura di una risposta, con ogni campo indicato dal suo tipo; l’esempio non contiene alcun valore. Il corpo ha il formato meconomy-offers-v1, l’ora di generazione, il numero di offerte, il numero di quelle trattenute perché un record non ha superato i nostri controlli, la licenza e l’ambito.

{
  "format": "meconomy-offers-v1",
  "vertical": "<mobile | internet | tv | phone>",
  "provider": "<string | null>",
  "generated_at": "<string>",
  "count": "<integer>",
  "withheld": "<integer>",
  "licence": {
    "id": "CC-BY-4.0",
    "url": "https://creativecommons.org/licenses/by/4.0/",
    "attribution": "MEconomy, meconomy.ch"
  },
  "scope": "<string>",
  "offers": [
    {
      "offer_id": "<string>",
      "provider": "<string>",
      "vertical": "<string>",
      "plan_name": "<string>",
      "currency": "<string>",
      "price_unit": "<string>",
      "price": "<number>",
      "price_after": "<number | null>",
      "promo_kind": "<string>",
      "promo_months": "<integer | null>",
      "valid_until": "<string | null>",
      "offer_until": "<string | null>",
      "list_price": "<number | null>",
      "setup_fee": "<number | null>",
      "setup_fee_promo": "<number | null>",
      "setup_fee_after": "<number | null>",
      "initial_free_months": "<integer | null>",
      "min_term_months": "<integer | null>",
      "condition_kind": "<string>",
      "availability_scope": "<string>",
      "now": {
        "price": "<number>",
        "price_after": "<number | null>",
        "display": "<string>",
        "cheapest_eligible": "<boolean>"
      },
      "evidence": {
        "source_url": "<string>",
        "read_at": "<string>",
        "last_checked_at": "<string>",
        "evidence_sha256": "<string>",
        "parser_version": "<string>",
        "reader": "<string>"
      }
    }
  ]
}

Campi di un’offerta
Campo	Tipo	Significato
`offer_id`	string	Identificativo stabile dell’offerta (l’impronta dell’abbonamento usata su meconomy.ch).
`provider`	string	Slug del fornitore, per esempio il valore da passare come parametro del fornitore.
`vertical`	string	Il confronto a cui appartiene l’offerta: mobile, internet, tv o phone.
`plan_name`	string	Nome dell’abbonamento come si chiama il prodotto.
`currency`	string	Valuta di ogni importo dell’offerta. CHF.
`price_unit`	string	Che cosa copre il prezzo: month, 28d, 30d, year, once o unit.
`price`	number	Prezzo di listino nella valuta, come rilevato dalla pagina del fornitore.
`price_after`	number \| null	Prezzo dopo la fine di una promozione limitata; null quando non è indicato.
`promo_kind`	string	Tipo di promozione: none, struck, indefinite_discount, duration, dated, lifetime o window.
`promo_months`	integer \| null	Durata in mesi di una promozione di tipo duration; null quando non è indicata.
`valid_until`	string \| null	Data in cui termina una promozione con data (YYYY-MM-DD); null quando non è indicata.
`offer_until`	string \| null	Data fino alla quale l’offerta può essere ordinata (YYYY-MM-DD); null quando non è indicata.
`list_price`	number \| null	Prezzo regolare che il fornitore mostra barrato; null quando non è indicato.
`setup_fee`	number \| null	Costo unico di attivazione o di installazione; null quando non è indicato.
`setup_fee_promo`	number \| null	Costo di installazione ridotto durante una promozione; null quando non è indicato.
`setup_fee_after`	number \| null	Costo di installazione dopo la fine della promozione; null quando non è indicato.
`initial_free_months`	integer \| null	Mesi senza costi all’inizio; null quando non sono indicati.
`min_term_months`	integer \| null	Durata minima del contratto in mesi; 0 significa nessuna.
`condition_kind`	string	A chi è destinata l’offerta: none, new_customer, existing_customer, youth, family, combo o other.
`availability_scope`	string	Dove è disponibile: national, regional o address.
`now`	object	Il prezzo in vigore a generated_at, calcolato dai campi della promozione.
`evidence`	object	Dove e quando sono state rilevate le cifre, e l’hash della pagina conservata.

Campi di now
Campo	Tipo	Significato
`price`	number	Prezzo in vigore a generated_at.
`price_after`	number \| null	Prezzo che segue al termine della promozione in corso; null quando non ce n’è.
`display`	string	regular, special o special_ended.
`cheapest_eligible`	boolean	Se l’offerta è la più conveniente del suo gruppo di abbonamenti che un cliente può ordinare.

Campi di evidence
Campo	Tipo	Significato
`source_url`	string	La pagina del fornitore da cui sono state rilevate le cifre (https).
`read_at`	string	Quando le cifre sono cambiate l’ultima volta su quella pagina (UTC, ISO 8601).
`last_checked_at`	string	Quando la pagina è stata verificata l’ultima volta (UTC, ISO 8601).
`evidence_sha256`	string	SHA-256 (64 hex) della pagina conservata da cui sono state rilevate le cifre.
`parser_version`	string	Commit (40 hex) del lettore che ha estratto le cifre.
`reader`	string	Chi ha consultato la pagina: parser, official o human.

Limiti

600 chiamate al giorno per chiave. Il conteggio riparte alle 00:00 UTC.
Le risposte 200 e 429 portano RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset (secondi fino all’azzeramento del conteggio); gli altri errori no.
Quando il limite è esaurito la risposta è 429 con Retry-After.

Errori

Un errore è {"error": {"code": "…", "message": "…"}} con lo stato indicato sotto.

Codici di errore
Codice	Stato	Significato
`missing_key`	401	Non è stata inviata alcuna intestazione Authorization.
`bad_key`	401	La chiave è malformata o sconosciuta.
`revoked`	403	La chiave è stata revocata.
`limit_reached`	429	Il limite giornaliero della chiave è esaurito; vedere Retry-After.
`unknown_vertical`	404	Il confronto indicato nel percorso non esiste.
`bad_request`	400	Un parametro non è consentito o non è valido.
`method_not_allowed`	405	È supportato soltanto GET.
`not_available`	503	La banca dati non è ancora attiva.
`upstream`	502	La banca dati non ha risposto.

Licenza e attribuzione

I dati sono concessi in licenza con CC BY 4.0. Citi «MEconomy, meconomy.ch» con un link a https://meconomy.ch ovunque li mostri. I prezzi sono fatti, così come li abbiamo rilevati al momento indicato; possono cambiare in qualsiasi momento e fa fede la pagina del fornitore. Nessuna garanzia. Possiamo revocare una chiave condivisa, rivenduta o usata oltre il suo limite.

I Suoi dati

Per ogni chiave conserviamo il nome dell’organizzazione o del progetto, un indirizzo e-mail di contatto, lo scopo indicato e il conteggio giornaliero delle chiamate per confronto; nessun indirizzo IP e nessun contenuto delle richieste. Li conserviamo finché la chiave è attiva. 12 mesi dopo la revoca di una chiave cancelliamo il nome, l’indirizzo e-mail di contatto e lo scopo; i conteggi giornalieri restano. Maggiori informazioni nell’informativa sulla protezione dei dati.

Modifiche

La versione 1 acquisisce soltanto nuovi campi. Una modifica che ne rimuove o ne rinomina uno diventa la versione 2, annunciata in questa pagina 90 giorni prima.