Il servizio Cerca Comuni appartiene all'API CAP e consente di verificare, ottenere ed aggiornare i codici città ISTAT ed i rispettivi Comuni associati.

Il codice ISTAT è un identificativo numerico attribuito dall'Istituto Nazionale di Statistica italiano ad ogni comune esistente o nuovo ed è utilizzato a fini statistici.

Si tratta di un codice alfanumerico composto da sei cifre: le prime tre cifre del codice identificano la provincia di appartenenza del comune, mentre le successive tre identificano il comune nell'ambito della propria provincia.  

Cerca Comuni è identificato dall’endpoint: GET https://cap.openapi.it/cerca_comuni

Il servizio è completamente gratuito e permette di ottenere il codice ISTAT a partire da una serie di parametri come:

• Città
• CAP
• Codice Catasto
• Regione
• Provincia
• Codice Fisco

Nella stessa richiesta possono essere combinati uno o più parametri.

Il campo nome (città) prevede un ricerca testuale e presenterà nei risultati tutte le città che contengono quel nome. Ad esempio se il parametro di ricerca per nome città è 'Roma', nella risposta verranno restituite altre città che includono "roma" come ad esempio Campagnano di Roma o Trevignano Romano. È possibile affinare la ricerca utilizzando gli altri parametri come provincia, regione e cap.

ESEMPIO RICHIESTA /cerca_comuni

Questo è un esempio di richiesta in cui abbiamo scelto come parametro il comune di Firenze

https://cap.openapi.it/cerca_comuni?comune=Firenze

La risposta potrà includere una o più città, in base ai parametri utilizzati, con le seguenti informazioni:

• Codice ISTAT
• Nome Comune
• Se quell'unità amministrativa è stata soppresso (true)

ESEMPIO RISPOSTA /cerca_comuni

Questo è un esempio di risposta:

{
  "data": {
      "istat": "48017",
      "comune": "Firenze",
      "suppressed":false 
     }
  ],
   "suppressed": []
  },
  "success": true,
  "message": "",
  "error": null
}

In caso di soppressione, il codice alfanumerico di sei caratteri che lo identificava al momento della soppressione resta assegnato al comune soppresso e non viene più riattribuito. In caso di modifica della denominazione, il codice rimane invariato e resta assegnato alla nuova denominazione.

Il codice ISTAT ottenuto potrà poi essere utilizzato per ottenere ulteriori informazioni sui Comuni tramite altri endpoint, come ad esempio Comuni Base o Advanced.