API e integrazioni
Le segnalazioni pubblicate sono disponibili tramite un'API JSON, tramite Open311 (compatibile con GIS come ArcGIS o QGIS e con i sistemi di manutenzione), tramite webhook e con un widget da integrare.
Principi
- Ogni sito ha la propria API, al proprio indirizzo: qui
https://scopemy.city. - Escono solo le segnalazioni pubblicate dopo la moderazione e i loro campi pubblici. Sul sito di un ente: le sue segnalazioni; su scopemy.city: tutte, tranne quelle che un ente mantiene interne.
- La lettura è aperta, senza chiave. Una chiave API (intestazione X-Api-Key), creata dall'amministrazione dell'ente, alza il limite; una chiave in scrittura permette di inviare richieste tramite Open311.
- Limite: 120 richieste al minuto per indirizzo IP, 600 per chiave. Oltre: risposta 429 con intestazione Retry-After.
- Paginazione a cursore (campo pagination.suivant, intestazione Link). Risposte in cache pubblica con ETag: inviate If-None-Match per ottenere un 304.
- Dati con licenza CC BY 4.0. Dati aperti
Specifica OpenAPI 3.1: openapi.yaml · openapi.json
curl -H 'Accept: application/json' 'https://scopemy.city/api/v1/signalements?statut=resolu&limite=20'API JSON
GET /api/v1/signalements
Elenco paginato delle segnalazioni pubblicate
| Parametro | Dove | Descrizione |
|---|---|---|
bbox |
query | Area minLng,minLat,maxLng,maxLat (WGS84). |
categorie |
query | Una o più categorie (codici separati da virgole). |
statut |
query | nouveau, en_cours, resolu o rejete (più valori separati da virgole). |
depuis |
query | Create a partire da questa data (AAAA-MM-GG). |
jusqua |
query | Create fino a questa data inclusa (AAAA-MM-GG). |
q |
query | Ricerca in titolo, indirizzo, descrizione, riferimento ed etichette. |
lang |
query | Lingua delle etichette (fr, de, it, en), tra quelle del sito. |
limite |
query | Segnalazioni per pagina (da 1 a 100, predefinito 50). |
curseur |
query | Cursore opaco della pagina successiva (pagination.suivant). |
GET /api/v1/signalements/{reference}
Una segnalazione pubblicata, per riferimento
| Parametro | Dove | Descrizione |
|---|---|---|
reference * |
path | Riferimento SC-XXXX-XXXX (o il vecchio FMC-XXXXXX). |
GET /api/v1/carte
Segnalazioni nell'area visibile della mappa, raggruppate a zoom basso
| Parametro | Dove | Descrizione |
|---|---|---|
bbox * |
query | Area visualizzata minLng,minLat,maxLng,maxLat (WGS84). |
zoom |
query | Livello di zoom Web Mercator (da 0 a 22). |
categorie |
query | Una o più categorie (codici separati da virgole). |
statut |
query | nouveau, en_cours, resolu o rejete (più valori separati da virgole). |
depuis |
query | Create a partire da questa data (AAAA-MM-GG). |
jusqua |
query | Create fino a questa data inclusa (AAAA-MM-GG). |
q |
query | Ricerca in titolo, indirizzo, descrizione, riferimento ed etichette. |
Open311 GeoReport v2
Solo formato JSON. I servizi sono le categorie del sito, le richieste sono le segnalazioni pubblicate; status vale open (nuova, in corso) o closed (risolta, respinta).
GET /open311/v2/discovery.json
Scoperta Open311
GET /open311/v2/services.json
Servizi (categorie del sito)
GET /open311/v2/requests.json
Richieste pubblicate (filtri Open311)
| Parametro | Dove | Descrizione |
|---|---|---|
service_request_id |
query | Uno o più riferimenti, separati da virgole. |
service_code |
query | Codice del servizio (categoria). |
status |
query | open (nuova, in corso) o closed (risolta, respinta). |
start_date |
query | Data ISO 8601 (al giorno). |
end_date |
query | Data ISO 8601 (al giorno, inclusa). |
page |
query | Pagina (estensione comune, da 1). |
page_size |
query | Dimensione della pagina (da 1 a 100, predefinito 50). |
POST /open311/v2/requests.json
Inviare una richiesta (chiave API in scrittura)
GET /open311/v2/requests/{id}.json
Una richiesta pubblicata
| Parametro | Dove | Descrizione |
|---|---|---|
id * |
path | Riferimento della segnalazione. |
Dati aperti
GET /donnees/signalements.csv
Esportazione CSV delle segnalazioni pubblicate (CC BY 4.0)
GET /donnees/signalements.geojson
Esportazione GeoJSON delle segnalazioni pubblicate (CC BY 4.0)
GET /donnees/statistiques.json
Statistiche pubbliche (volume, tempi mediani, tasso di risoluzione)
Webhook
Un ente può abbonare un indirizzo https a questi eventi (amministrazione, pagina API). Inviamo un POST JSON entro 5 minuti; una segnalazione non ancora pubblicata contiene solo riferimento, categoria, stati, posizione e date.
| Evento | Descrizione |
|---|---|
signalement.cree | Segnalazione creata (in attesa di moderazione) |
signalement.publie | Segnalazione pubblicata |
signalement.statut | Stato cambiato (data.ancien_statut indica il precedente) |
signalement.reponse | Risposta ufficiale aggiunta o modificata |
signalement.affecte | Assegnata a un servizio o a un incaricato (portale dei servizi) |
Ogni invio è firmato nell'intestazione X-Scopemy-Signature: t=marca temporale,v1=HMAC-SHA256 del testo «t.corpo» con il vostro segreto. Verificatelo in tempo costante e rifiutate marche più vecchie di 5 minuti. X-Scopemy-Delivery fornisce un identificativo stabile: ignorate un invio già ricevuto.
$corps = file_get_contents('php://input');
[$t, $sig] = sscanf($_SERVER['HTTP_X_SCOPEMY_SIGNATURE'] ?? '', 't=%d,v1=%s');
$attendu = hash_hmac('sha256', $t . '.' . $corps, $secret);
if (!$sig || !hash_equals($attendu, $sig) || abs(time() - $t) > 300) {
http_response_code(400); exit;
}
$evenement = json_decode($corps, true); // id, type, tenant, data.signalement
http_response_code(204);Qualsiasi risposta 2xx vale come ricezione. Altrimenti riproviamo fino a 8 volte, raddoppiando l'attesa (1 min, 2 min, 4 min…, al massimo 6 h). I reindirizzamenti non sono seguiti.
Widget per il sito del comune
Incollate questo codice in una pagina del sito del comune per mostrare la mappa e le ultime segnalazioni, con il marchio dell'ente. Il sito deve prima essere autorizzato nell'amministrazione (pagina API).
<script src="https://scopemy.city/embed.js" data-vue="carte-liste" data-hauteur="560" async></script>Opzioni: data-vue (carte-liste, carte o liste), data-hauteur (in pixel, o auto), data-lang (fr, de, it, en). Il widget non installa cookie.