cap.openapi.json

{"openapi":"3.0.0","info":{"description":"This service allows you to search italian cities and get their istat and cap codes. <br> <br> <h2>Testing</h2>Please note that the sandbox environment is loaded with a limited dataset and is intended to be used for testing purposes. Some search parameters might not work or return always the same data.","version":"1.0.0","title":"Cap","termsOfService":"https://openapi.it/en/terms-and-conditions","contact":{"url":"https://openapi.it/en/support","name":"Support"},"license":{"name":"Apache 2.0","url":"http://www.apache.org/licenses/LICENSE-2.0.html"}},"servers":[{"url":"https://cap.openapi.it","description":"Production"},{"url":"https://test.cap.openapi.it","description":"Sandbox"}],"tags":[{"name":"Comuni"},{"name":"Cap"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{}},"paths":{"/cerca_comuni":{"get":{"tags":["Comuni"],"summary":"Search cities by name, region and/or province","description":"This method allows you to search italian cities and get their istat code","parameters":[{"name":"comune","in":"query","description":"Name of the city","schema":{"type":"string"}},{"name":"cap","in":"query","description":"Cap of the city","required":false,"schema":{"type":"string"}},{"name":"istat","in":"query","description":"Istat code of the city","required":false,"schema":{"type":"string"}},{"name":"codice_catasto","in":"query","description":"Land registry code of the city","required":false,"schema":{"type":"string"}},{"name":"regione","in":"query","description":"Region of the city","required":false,"schema":{"type":"string"}},{"name":"provincia","in":"query","description":"Province of the city","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"istat":{"type":"string"},"comune":{"type":"string"},"suppressed":{"type":"boolean"}}}},"success":{"type":"boolean"},"message":{"type":"string"},"error":{"type":"integer"}}},"example":{"data":[{"istat":"70006","comune":"Campobasso","suppressed":false},{"istat":"70078","comune":"Termoli","suppressed":false},{"istat":"94023","comune":"Isernia","suppressed":false},{"istat":"94052","comune":"Venafro","suppressed":false}],"success":true,"message":"","error":null}}}}}}},"/comuni_base/{istat_code}":{"get":{"tags":["Comuni"],"summary":"Get basic information about a city","description":"basic information about city","parameters":[{"name":"istat_code","in":"path","description":"Istat code of the city, you can find it in the search results","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"istat":{"type":"string"},"comune":{"type":"string"},"regione":{"type":"string"},"provincia":{"type":"string"},"cap":{"type":"array","items":{"type":"string"}}}},"success":{"type":"boolean"},"message":{"type":"string"},"error":{"type":"integer"}}},"example":{"data":{"istat":"70006","comune":"Campobasso","regione":"Molise","provincia":"Campobasso","cap":["86100"]},"success":true,"message":"","error":null}}}}}}},"/comuni_advance/{istat_code}":{"get":{"tags":["Comuni"],"summary":"Get more information about a city","description":"advanced information about a city","parameters":[{"name":"istat_code","in":"path","description":"Istat code of the city, you can find it in the search results","schema":{"type":"string"},"required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"istat":{"type":"string"},"comune":{"type":"string"},"regione":{"type":"string"},"provincia":{"type":"string"},"prefisso":{"type":"string"},"cod_fisco":{"type":"string","description":"This code, also known as 'codice Belfiore' can be used to validate Italian fiscal codes"},"superficie":{"type":"integer","format":"int32","description":"Surface in square kilometers"},"num_residenti":{"type":"integer","format":"int32"},"nome_abitanti":{"type":"string"},"patrono":{"type":"object","properties":{"nome":{"type":"string"},"data":{"type":"string"}}},"municipio":{"type":"object","properties":{"municipio":{"type":"string"}}},"istat_old":{"type":"string","format":"nullable"},"sigla_provincia":{"type":"string"},"email":{"type":"string"},"pec":{"type":"string"},"tel":{"type":"string"},"fax":{"type":"string"},"frazioni":{"type":"array","items":{"type":"string"}},"cap":{"type":"array","items":{"type":"string"}}}},"success":{"type":"boolean"},"message":{"type":"string"},"error":{"type":"integer"}}},"example":{"data":{"istat":"58091","comune":"Roma","regione":"Lazio","provincia":"Roma","prefisso":"06","cod_fisco":"H501","superficie":1308,"num_residenti":2770226,"nome_abitanti":"Romani","patrono":{"nome":"SS. Pietro e Paolo","data":"29 giugno"},"municipio":{"municipio":"Via del Campidoglio"},"istat_old":null,"sigla_provincia":"RM","email":"ld.gabinetto@comune.roma.it","pec":"protocollo.segretariato@pec.comune.roma.it","tel":"+39 06/67102001","fax":"+39 06/67103590","frazioni":["Borgo Lotti",".."],"cap":["00118","..."]},"success":true,"message":"","error":null}}}}}}},"/cap/{cap}":{"get":{"tags":["Cap"],"summary":"Get a list of cities that match a cap","parameters":[{"name":"cap","in":"path","description":"A cap code","schema":{"type":"string"},"required":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"comuni":{"type":"array","items":{"type":"object","properties":{"istat":{"type":"string"},"comune":{"type":"string"},"frazione":{"description":"This field is only present if the CAP code belongs to an hamlet","nullable":true,"type":"string"},"comune_istat":{"description":"The istat code of the city the hamlet belongs to. If the CAP does not belong to a hamlet, this field matches the `istat` field. See `Pescia` in the example object.","type":"string"}}}},"regione":{"type":"string"},"provincia":{"type":"string"},"sigla_provincia":{"type":"string","example":"RM"}}},"success":{"type":"boolean"},"message":{"type":"string"},"error":{"type":"integer"}}},"example":{"data":{"comuni":[{"istat":"1016","comune":"Balangero","frazione":null,"comune_istat":"1016"},{"istat":"1019","comune":"Balme","frazione":null,"comune_istat":"1019"},{"istat":"1021","comune":"Barbania","frazione":null,"comune_istat":"1021"},{"istat":"4701210002","comune":"Pescia","frazione":"Castelvecchio","comune_istat":"47012"}],"provincia":"Torino","sigla_provincia":"TO","regione":"Piemonte"},"success":true,"message":"","error":null}}}}}}},"/regioni":{"get":{"tags":["Regioni"],"summary":"Get the list of italian regions","parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"regione":{"type":"string"},"capoluogo":{"type":"string"},"superficie":{"type":"number"},"num_residenti":{"type":"integer"},"num_province":{"type":"integer"},"num_comuni":{"type":"integer"},"presidente":{"type":"string"},"cod_fiscale":{"type":"string"},"piva":{"type":"string"},"pec":{"type":"string"},"sito":{"type":"string"},"sede":{"type":"string"},"istat":{"type":"string"}}}},"success":{"type":"boolean"},"message":{"type":"string"},"error":{"type":"integer"}}},"example":{"data":[{"regione":"Abruzzo","capoluogo":"L'Aquila","superficie":10831.84,"num_residenti":1305770,"num_comuni":305,"presidente":"Marco Marsilio","cod_fiscale":"80003170661","piva":"","pec":"urp@pec.regione.abruzzo.it","sito":"www.regione.abruzzo.it","sede":"Regione Abruzzo / Palazzo Silone - Via Leonardo da Vinci 6, 67100 L'Aquila","istat":"13","num_province":4},{"...":"..."}],"success":true,"message":"","error":null}}}}}}},"/province":{"get":{"tags":["Province"],"summary":"Get the list of italian provinces","parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"sigla":{"type":"string"},"provincia":{"type":"string"},"superficie":{"type":"number"},"residenti":{"type":"integer"},"num_comuni":{"type":"integer"},"istat":{"type":"string"},"regione":{"type":"string"}}}},"success":{"type":"boolean"},"message":{"type":"string"},"error":{"type":"integer"}}},"example":{"data":[{"sigla":"AG","provincia":"Agrigento","superficie":3052.59,"residenti":446081,"num_comuni":43,"istat":"084","regione":"Sicilia"},{"...":"..."}],"success":true,"message":"","error":null}}}}}}},"/province/{code}":{"get":{"tags":["Province"],"summary":"Get an italian province","parameters":[{"name":"code","in":"path","description":"The province code, like RM, MI, TO etc...","example":"AG","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"sigla":{"type":"string"},"provincia":{"type":"string"},"superficie":{"type":"number"},"residenti":{"type":"integer"},"num_comuni":{"type":"integer"},"istat":{"type":"string"},"regione":{"type":"string"}}},"success":{"type":"boolean"},"message":{"type":"string"},"error":{"type":"integer"}}},"example":{"data":{"sigla":"AG","provincia":"Agrigento","superficie":3052.59,"residenti":446081,"num_comuni":43,"istat":"084","regione":"Sicilia"},"success":true,"message":"","error":null}}}}}}},"/comuni_soppressi":{"get":{"description":"offering information on discontinued municipal entities.","tags":["Comuni"],"summary":"Get a list of suppressed municipalities","parameters":[{"name":"sigla_provincia","in":"query","description":"The province code, like RM, MI, TO etc...","example":"AG","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"istat":{"type":"string"},"comune":{"type":"string"},"cod_fisco":{"type":"number"},"sigla_provincia":{"type":"string"},"regione":{"type":"string"},"provincia":{"type":"string"}}}},"success":{"type":"boolean"},"message":{"type":"string"},"error":{"type":"integer"}}},"example":{"data":[{"istat":"24011","comune":"Barbarano Vicentino","cod_fisco":"A627","sigla_provincia":"VI","regione":"Veneto","provincia":"Vicenza"},{"...":"..."}],"success":true,"message":"","error":null}}}}}}},"/citta_metropolitane":{"get":{"description":"offering information on metropolitan cities, providing details about metropolitan areas and their features.","tags":["Comuni"],"summary":"Get a list of Italian metropolitan cities","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"denominazione":{"type":"string"},"capoluogo":{"type":"string"},"popolazione":{"type":"integer","format":"int32"},"superficie":{"type":"integer","format":"int32"},"densita":{"type":"integer","format":"int32"},"num_comuni":{"type":"integer","format":"int32"}}}},"success":{"type":"boolean"},"message":{"type":"string"},"error":{"type":"integer"}}},"example":{"data":[{"denominazione":"MESSINA","capoluogo":"Messina","popolazione":631297,"superficie":3266,"densita":193,"num_comuni":108},{"...":"..."}],"success":true,"message":"","error":null}}}}}}}},"externalDocs":{"description":"First time here? Generate a new access token","url":"https://console.openapi.com/oauth"},"security":[{"bearerAuth":[]}]}