{"openapi":"3.0.3","info":{"title":"Evitalya Livability Score API","version":"1.0.0","description":"One HTTP call returns a 0-100 livability score for any address in Italy, computed from 111 metrics in six categories — safety, services, mobility, environment, real estate and natural risk — derived from official sources (ISTAT, Ministry of the Interior, ISPRA, INGV, ARPA, AGENAS, MUR, OMI/Agenzia delle Entrate, OpenStreetMap, Copernicus/EEA).\n\nSelf-service: sign up, verify your email, take the key from your account. No contract and no sales call. Quotas are monthly, not daily, so a nightly import or a portfolio recomputation can spend a month's allowance in one run.\n\nPlans:\n- `free`: 100 calls/month, up to 5 calls/minute, free (overall and category scores; no per-category reliability)\n- `starter`: 5,000 calls/month, up to 10 calls/minute, 49 EUR/month\n- `pro`: 50,000 calls/month, up to 30 calls/minute, 249 EUR/month\n- `scale`: 500,000 calls/month, up to 60 calls/minute, 990 EUR/month\n\nCategory keys are codes (`safety`, `enviro`), never labels: an integration does not break when the site language changes.\n\nWhat you may do with the output is set by the terms of service (https://evitalya.com/terms.html). Source licences and required attribution are at https://evitalya.com/attribution.html.","termsOfService":"https://evitalya.com/terms.html","contact":{"name":"Evitalya","url":"https://evitalya.com/api.html"}},"servers":[{"url":"https://evitalya.com"}],"tags":[{"name":"score","description":"Scoring of a single address."},{"name":"plans","description":"The published price list."}],"paths":{"/v1/score":{"post":{"tags":["score"],"operationId":"scoreAddress","summary":"Score one Italian address or point","description":"Send either `address` or both `lat` and `lon`, never both. With coordinates no geocoding happens: the comune is taken from the ISTAT census section that contains the point, which is the right input for enriching listings that already carry latitude and longitude. Computes the score and returns it. Counts one call against the monthly quota. Typical latency is a few seconds: the computation is done on request, not read from a cache of precomputed values.","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddressRequest"},"examples":{"address":{"summary":"By address","value":{"address":"Via Vigevano 12, Milano"}},"coordinates":{"summary":"By coordinates","value":{"lat":45.452,"lon":9.169}}}}}},"responses":{"200":{"description":"Score computed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Score"}}}},"401":{"description":"`api_key_required` or `invalid_api_key`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}},"404":{"description":"`address_not_found`: the address could not be geocoded; `coordinates_outside_italy`: the point is in no Italian comune (sea, abroad, San Marino, Vatican).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}},"422":{"description":"`address_and_coordinates`: both were sent; `address_or_coordinates_required`: neither, or only one of `lat` and `lon`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}},"429":{"description":"`monthly_quota_exceeded` (the plan quota is spent: see `upgrade`) or `rate_limit_exceeded` (too many calls this minute: wait `Retry-After` seconds). Every response to a key carries `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}},"500":{"description":"`scoring_failed`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}},"502":{"description":"`geocoder_unavailable`: temporary.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errore"}}}}}}},"/v1/plans":{"get":{"tags":["plans"],"operationId":"listPlans","summary":"The live price list","description":"Readable without a key. It is the pricing page, in JSON.","responses":{"200":{"description":"The plans.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Plans"}}}}}}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Issued from your account page. Shown once."}},"schemas":{"AddressRequest":{"type":"object","description":"Either `address`, or both `lat` and `lon`.","properties":{"address":{"type":"string","maxLength":200,"description":"A street address in Italy, free form.","example":"Via Vigevano 12, Milano"},"lat":{"type":"number","minimum":35.0,"maximum":48.0,"description":"Latitude, WGS84.","example":45.452},"lon":{"type":"number","minimum":6.0,"maximum":19.0,"description":"Longitude, WGS84.","example":9.169}}},"CategoryScore":{"type":"object","properties":{"score":{"type":"number","description":"0-100."},"reliability":{"type":"number","description":"0-1. Only on plans that return the full report."},"measured_metrics":{"type":"integer"},"total_metrics":{"type":"integer"}}},"Score":{"type":"object","properties":{"schema":{"type":"string","enum":["evitalya.score.v1"]},"plan":{"type":"string"},"address":{"type":"object","properties":{"input":{"type":"string","nullable":true,"description":"The address sent; null with coordinates."},"source":{"type":"string","enum":["address","coordinates"]},"resolved":{"type":"string"},"lat":{"type":"number"},"lon":{"type":"number"},"istat":{"type":"string","description":"ISTAT code of the comune."},"comune":{"type":"string"},"provincia":{"type":"string"}}},"score":{"type":"number","description":"Overall, 0-100."},"reliability":{"type":"number","description":"0-1."},"reliability_code":{"type":"string","enum":["very_high","high","good","medium","low"],"description":"Reliability band of the score, language-independent. Derived from the same thresholds the engine uses."},"categories":{"type":"object","description":"Keyed by category code.","additionalProperties":{"$ref":"#/components/schemas/CategoryScore"}},"measured_metrics":{"type":"integer"},"total_metrics":{"type":"integer"},"insufficient_data":{"type":"array","items":{"type":"object","properties":{"category":{"type":"string","description":"Category code."},"measured":{"type":"integer","description":"Metrics measured directly."},"total":{"type":"integer","description":"Metrics in the category."},"ratio":{"type":"number","description":"measured / total, rounded to 3."}},"required":["category","measured","total","ratio"]},"description":"Categories that are NOT measured well enough to be read, weakest first, each with the numbers behind it. It separates «measured as bad» from «not measured»: without it a low score for missing data looks like a low score for a bad place."},"elapsed_s":{"type":"number"}}},"Plans":{"type":"object","properties":{"schema":{"type":"string","enum":["evitalya.plans.v1"]},"currency":{"type":"string"},"plans":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"calls_per_month":{"type":"integer"},"calls_per_minute":{"type":"integer"},"price_eur":{"type":"number"},"eur_per_1000_calls":{"type":"number"},"full_report":{"type":"boolean"},"recommended":{"type":"boolean"}}}}}},"Errore":{"type":"object","properties":{"error":{"type":"string","description":"Stable machine code."},"detail":{"type":"string","description":"Human text, in the language of the request."}}}}}}