{"openapi":"3.1.0","info":{"title":"MobilityLens Products API","version":"1.0.0","description":"Coverage is limited to the Metropolitan City of Torino, Piemonte. Other Italian regions and provinces are rejected. PriceLens is not offered in this release. Use a signed-in user access token as Authorization: Bearer <access_token>. The platform UI can also use its same-origin session cookies. Identity and token balance come from the verified user session. Unknown query parameters are rejected. All data responses use Cache-Control: no-store. See /prodotti/api/documentazione for the quick start."},"servers":[{"url":"/","description":"Current MobilityLens origin; use HTTPS outside local development."}],"security":[{"bearerAuth":[]}],"paths":{"/api/v1/projects":{"get":{"operationId":"listProjects","summary":"Search projects","description":"Piemonte/Torino scope is always enforced. Costs 1 token per returned record, including cached reads. For the next page, pass meta.pagination.next_cursor as cursor and keep the same filters.","security":[{"bearerAuth":[]}],"parameters":[{"name":"X-Request-Id","in":"header","required":false,"description":"Optional unique operation ID. Generated when omitted. Reusing an ID already recorded for a charged operation returns 409 REQUEST_ALREADY_PROCESSED; the previous response is not replayed.","schema":{"type":"string","pattern":"^[A-Za-z0-9:_-]{1,128}$","maxLength":128}},{"name":"limit","in":"query","description":"Rows per page: at most 250, or 5000 with download_format.","required":false,"schema":{"type":"integer","minimum":1,"maximum":5000,"default":10}},{"name":"offset","in":"query","description":"Rows to skip.","required":false,"schema":{"type":"integer","minimum":0,"maximum":100000,"default":0}},{"name":"region","in":"query","description":"Fixed release region; injected when omitted.","required":false,"schema":{"type":"string","const":"Piemonte","default":"Piemonte"}},{"name":"province","in":"query","description":"Fixed metropolitan area; injected when omitted.","required":false,"schema":{"type":"string","const":"Torino","default":"Torino"}},{"name":"comune","in":"query","description":"Municipality. Repeat the parameter or separate values with commas.","required":false,"schema":{"type":"array","items":{"type":"string","minLength":1,"maxLength":128},"minItems":1},"style":"form","explode":true},{"name":"area_name","in":"query","description":"Area name. Repeat the parameter or separate values with commas.","required":false,"schema":{"type":"array","items":{"type":"string","minLength":1,"maxLength":128},"minItems":1},"style":"form","explode":true},{"name":"quartiere","in":"query","description":"Neighborhood. Repeat the parameter or separate values with commas.","required":false,"schema":{"type":"array","items":{"type":"string","minLength":1,"maxLength":128},"minItems":1},"style":"form","explode":true},{"name":"macrocategory","in":"query","description":"Category code from project facets. Repeat the parameter; commas are part of the value.","required":false,"schema":{"type":"array","items":{"type":"string","minLength":1,"maxLength":128},"minItems":1},"style":"form","explode":true},{"name":"normalized_project_category","in":"query","description":"Italian project microcategory; use project facets. Repeat the parameter; commas are part of the value.","required":false,"schema":{"type":"array","items":{"type":"string","minLength":1,"maxLength":128},"minItems":1},"style":"form","explode":true},{"name":"timing_status","in":"query","description":"Timing status; ignored when project_status is supplied. Repeat the parameter or separate values with commas.","required":false,"schema":{"type":"array","items":{"type":"string","minLength":1,"maxLength":128},"minItems":1},"style":"form","explode":true},{"name":"project_status","in":"query","description":"Project status from project facets. Repeat the parameter or separate values with commas.","required":false,"schema":{"type":"array","items":{"type":"string","minLength":1,"maxLength":128},"minItems":1},"style":"form","explode":true},{"name":"keyword","in":"query","description":"Text search.","required":false,"schema":{"type":"string","minLength":1,"maxLength":128}},{"name":"start_year_from","in":"query","description":"Minimum start year, inclusive.","required":false,"schema":{"type":"integer","minimum":1900,"maximum":2200}},{"name":"start_year_to","in":"query","description":"Maximum start year, inclusive.","required":false,"schema":{"type":"integer","minimum":1900,"maximum":2200}},{"name":"has_coordinates","in":"query","description":"Filter by coordinate availability.","required":false,"schema":{"type":"boolean"}},{"name":"cursor","in":"query","description":"Opaque next_cursor from the preceding page. Takes precedence over offset unless sample_mode is used.","required":false,"schema":{"type":"string","maxLength":512}},{"name":"sample_mode","in":"query","description":"Optional category-balanced sample. Use offset pagination with this mode.","required":false,"schema":{"type":"string","enum":["stratified"]}},{"name":"download_format","in":"query","description":"Marks an export for audit. The HTTP response remains a JSON envelope; convert data to the selected format in your client.","required":false,"schema":{"type":"string","enum":["csv","json","geojson"]}}],"responses":{"200":{"description":"Success.","headers":{"Cache-Control":{"description":"Responses must not be stored.","schema":{"type":"string","const":"private, no-store"}},"X-Request-Id":{"description":"Request identifier for diagnostics.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectsResponse"}}}},"400":{"description":"Invalid or unsupported input. Correct the request before retrying.","headers":{"Cache-Control":{"description":"Responses must not be stored.","schema":{"type":"string","const":"private, no-store"}},"X-Request-Id":{"description":"Request identifier for diagnostics.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or expired user session. Sign in again or refresh your access token.","headers":{"Cache-Control":{"description":"Responses must not be stored.","schema":{"type":"string","const":"private, no-store"}},"X-Request-Id":{"description":"Request identifier for diagnostics.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient tokens or a request origin that is not allowed.","headers":{"Cache-Control":{"description":"Responses must not be stored.","schema":{"type":"string","const":"private, no-store"}},"X-Request-Id":{"description":"Request identifier for diagnostics.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"REQUEST_ALREADY_PROCESSED: this charged operation ID is already recorded. Check your balance before starting a new operation. No response replay.","headers":{"Cache-Control":{"description":"Responses must not be stored.","schema":{"type":"string","const":"private, no-store"}},"X-Request-Id":{"description":"Request identifier for diagnostics.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Request rate exceeded. Wait before retrying.","headers":{"Cache-Control":{"description":"Responses must not be stored.","schema":{"type":"string","const":"private, no-store"}},"X-Request-Id":{"description":"Request identifier for diagnostics.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required service is temporarily unavailable.","headers":{"Cache-Control":{"description":"Responses must not be stored.","schema":{"type":"string","const":"private, no-store"}},"X-Request-Id":{"description":"Request identifier for diagnostics.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"The request timed out. Check the balance before retrying a charged operation.","headers":{"Cache-Control":{"description":"Responses must not be stored.","schema":{"type":"string","const":"private, no-store"}},"X-Request-Id":{"description":"Request identifier for diagnostics.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/projects/facets":{"get":{"operationId":"getProjectFacets","summary":"Available project filters","description":"No token charge. Pass selected location values to narrow the available filters.","security":[{"bearerAuth":[]}],"parameters":[{"name":"X-Request-Id","in":"header","required":false,"description":"Optional unique operation ID. Generated when omitted. Reusing an ID already recorded for a charged operation returns 409 REQUEST_ALREADY_PROCESSED; the previous response is not replayed.","schema":{"type":"string","pattern":"^[A-Za-z0-9:_-]{1,128}$","maxLength":128}},{"name":"region","in":"query","description":"Fixed release region; injected when omitted.","required":false,"schema":{"type":"string","const":"Piemonte","default":"Piemonte"}},{"name":"province","in":"query","description":"Fixed metropolitan area; injected when omitted.","required":false,"schema":{"type":"string","const":"Torino","default":"Torino"}},{"name":"comune","in":"query","description":"Municipality. Repeat the parameter or separate values with commas.","required":false,"schema":{"type":"array","items":{"type":"string","minLength":1,"maxLength":128},"minItems":1},"style":"form","explode":true}],"responses":{"200":{"description":"Success.","headers":{"Cache-Control":{"description":"Responses must not be stored.","schema":{"type":"string","const":"private, no-store"}},"X-Request-Id":{"description":"Request identifier for diagnostics.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectFacetsResponse"}}}},"400":{"description":"Invalid or unsupported input. Correct the request before retrying.","headers":{"Cache-Control":{"description":"Responses must not be stored.","schema":{"type":"string","const":"private, no-store"}},"X-Request-Id":{"description":"Request identifier for diagnostics.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or expired user session. Sign in again or refresh your access token.","headers":{"Cache-Control":{"description":"Responses must not be stored.","schema":{"type":"string","const":"private, no-store"}},"X-Request-Id":{"description":"Request identifier for diagnostics.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient tokens or a request origin that is not allowed.","headers":{"Cache-Control":{"description":"Responses must not be stored.","schema":{"type":"string","const":"private, no-store"}},"X-Request-Id":{"description":"Request identifier for diagnostics.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"REQUEST_ALREADY_PROCESSED: this charged operation ID is already recorded. Check your balance before starting a new operation. No response replay.","headers":{"Cache-Control":{"description":"Responses must not be stored.","schema":{"type":"string","const":"private, no-store"}},"X-Request-Id":{"description":"Request identifier for diagnostics.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Request rate exceeded. Wait before retrying.","headers":{"Cache-Control":{"description":"Responses must not be stored.","schema":{"type":"string","const":"private, no-store"}},"X-Request-Id":{"description":"Request identifier for diagnostics.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required service is temporarily unavailable.","headers":{"Cache-Control":{"description":"Responses must not be stored.","schema":{"type":"string","const":"private, no-store"}},"X-Request-Id":{"description":"Request identifier for diagnostics.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"The request timed out. Check the balance before retrying a charged operation.","headers":{"Cache-Control":{"description":"Responses must not be stored.","schema":{"type":"string","const":"private, no-store"}},"X-Request-Id":{"description":"Request identifier for diagnostics.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/funding":{"get":{"operationId":"listFunding","summary":"Project funding and timeline","description":"Piemonte/Torino scope is always enforced, including spatial selections. Costs 1 token per returned record. Summary and series describe the filtered dataset; data.records is paginated. Date filters take precedence over corresponding year filters.","security":[{"bearerAuth":[]}],"parameters":[{"name":"X-Request-Id","in":"header","required":false,"description":"Optional unique operation ID. Generated when omitted. Reusing an ID already recorded for a charged operation returns 409 REQUEST_ALREADY_PROCESSED; the previous response is not replayed.","schema":{"type":"string","pattern":"^[A-Za-z0-9:_-]{1,128}$","maxLength":128}},{"name":"limit","in":"query","description":"Rows per page: at most 250, or 5000 with download_format.","required":false,"schema":{"type":"integer","minimum":1,"maximum":5000,"default":10}},{"name":"offset","in":"query","description":"Rows to skip.","required":false,"schema":{"type":"integer","minimum":0,"maximum":100000,"default":0}},{"name":"region","in":"query","description":"Fixed release region; injected when omitted.","required":false,"schema":{"type":"string","const":"Piemonte","default":"Piemonte"}},{"name":"province","in":"query","description":"Fixed metropolitan area; injected when omitted.","required":false,"schema":{"type":"string","const":"Torino","default":"Torino"}},{"name":"comune","in":"query","description":"Municipality. Repeat the parameter or separate values with commas.","required":false,"schema":{"type":"array","items":{"type":"string","minLength":1,"maxLength":128},"minItems":1},"style":"form","explode":true},{"name":"area_name","in":"query","description":"Area name. Repeat the parameter or separate values with commas.","required":false,"schema":{"type":"array","items":{"type":"string","minLength":1,"maxLength":128},"minItems":1},"style":"form","explode":true},{"name":"quartiere","in":"query","description":"Neighborhood. Repeat the parameter or separate values with commas.","required":false,"schema":{"type":"array","items":{"type":"string","minLength":1,"maxLength":128},"minItems":1},"style":"form","explode":true},{"name":"macrocategory","in":"query","description":"Category code from project facets. Repeat the parameter; commas are part of the value.","required":false,"schema":{"type":"array","items":{"type":"string","minLength":1,"maxLength":128},"minItems":1},"style":"form","explode":true},{"name":"normalized_project_category","in":"query","description":"Italian project microcategory; use project facets. Repeat the parameter; commas are part of the value.","required":false,"schema":{"type":"array","items":{"type":"string","minLength":1,"maxLength":128},"minItems":1},"style":"form","explode":true},{"name":"timing_status","in":"query","description":"Timing status; ignored when project_status is supplied. Repeat the parameter or separate values with commas.","required":false,"schema":{"type":"array","items":{"type":"string","minLength":1,"maxLength":128},"minItems":1},"style":"form","explode":true},{"name":"project_status","in":"query","description":"Project status from project facets. Repeat the parameter or separate values with commas.","required":false,"schema":{"type":"array","items":{"type":"string","minLength":1,"maxLength":128},"minItems":1},"style":"form","explode":true},{"name":"keyword","in":"query","description":"Text search.","required":false,"schema":{"type":"string","minLength":1,"maxLength":128}},{"name":"start_year_from","in":"query","description":"Minimum start year, inclusive.","required":false,"schema":{"type":"integer","minimum":1900,"maximum":2200}},{"name":"start_year_to","in":"query","description":"Maximum start year, inclusive.","required":false,"schema":{"type":"integer","minimum":1900,"maximum":2200}},{"name":"has_coordinates","in":"query","description":"Filter by coordinate availability.","required":false,"schema":{"type":"boolean"}},{"name":"project_source_group","in":"query","description":"Project source group. Repeat the parameter or separate values with commas.","required":false,"schema":{"type":"array","items":{"type":"string","minLength":1,"maxLength":128},"minItems":1},"style":"form","explode":true},{"name":"finish_year_from","in":"query","description":"Minimum finish year, inclusive.","required":false,"schema":{"type":"integer","minimum":1900,"maximum":2200}},{"name":"finish_year_to","in":"query","description":"Maximum finish year, inclusive.","required":false,"schema":{"type":"integer","minimum":1900,"maximum":2200}},{"name":"start_date_from","in":"query","description":"Inclusive date boundary (YYYY-MM-DD).","required":false,"schema":{"type":"string","format":"date"}},{"name":"start_date_to","in":"query","description":"Inclusive date boundary (YYYY-MM-DD).","required":false,"schema":{"type":"string","format":"date"}},{"name":"finish_date_from","in":"query","description":"Inclusive date boundary (YYYY-MM-DD).","required":false,"schema":{"type":"string","format":"date"}},{"name":"finish_date_to","in":"query","description":"Inclusive date boundary (YYYY-MM-DD).","required":false,"schema":{"type":"string","format":"date"}},{"name":"has_finish_year","in":"query","description":"Filter by finish-year availability.","required":false,"schema":{"type":"boolean"}},{"name":"min_funding_eur","in":"query","description":"Minimum funding in euros.","required":false,"schema":{"type":"number","minimum":0,"maximum":1000000000000,"multipleOf":0.01}},{"name":"max_funding_eur","in":"query","description":"Maximum funding in euros.","required":false,"schema":{"type":"number","minimum":0,"maximum":1000000000000,"multipleOf":0.01}},{"name":"big_projects_only","in":"query","description":"When true, select projects with funding of at least EUR 10 million.","required":false,"schema":{"type":"boolean"}},{"name":"min_lat","in":"query","description":"South latitude; provide all four bounds for a bounding box.","required":false,"schema":{"type":"number","minimum":-90,"maximum":90}},{"name":"max_lat","in":"query","description":"North latitude.","required":false,"schema":{"type":"number","minimum":-90,"maximum":90}},{"name":"min_lon","in":"query","description":"West longitude.","required":false,"schema":{"type":"number","minimum":-180,"maximum":180}},{"name":"max_lon","in":"query","description":"East longitude.","required":false,"schema":{"type":"number","minimum":-180,"maximum":180}},{"name":"center_lat","in":"query","description":"Circle latitude; requires center_lon and radius_km.","required":false,"schema":{"type":"number","minimum":-90,"maximum":90}},{"name":"center_lon","in":"query","description":"Circle longitude; requires center_lat and radius_km.","required":false,"schema":{"type":"number","minimum":-180,"maximum":180}},{"name":"radius_km","in":"query","description":"Circle radius in km; requires center_lat and center_lon.","required":false,"schema":{"type":"number","exclusiveMinimum":0,"maximum":1000}},{"name":"polygon","in":"query","description":"3–80 lat,lon pairs separated by semicolons. Example: 45.06,7.68;45.08,7.68;45.06,7.70.","required":false,"schema":{"type":"string","maxLength":4096}},{"name":"timeline_basis","in":"query","description":"Date used to group the timeline. Year aliases remain accepted.","required":false,"schema":{"type":"string","enum":["start_date","finish_date","start_year","finish_year"],"default":"start_date"}},{"name":"timeline_mode","in":"query","description":"Timeline scope.","required":false,"schema":{"type":"string","enum":["all","funded","future"],"default":"all"}},{"name":"download_format","in":"query","description":"Marks an export for audit. The HTTP response remains a JSON envelope; convert data to the selected format in your client.","required":false,"schema":{"type":"string","enum":["csv","json","geojson"]}}],"responses":{"200":{"description":"Success.","headers":{"Cache-Control":{"description":"Responses must not be stored.","schema":{"type":"string","const":"private, no-store"}},"X-Request-Id":{"description":"Request identifier for diagnostics.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FundingResponse"}}}},"400":{"description":"Invalid or unsupported input. Correct the request before retrying.","headers":{"Cache-Control":{"description":"Responses must not be stored.","schema":{"type":"string","const":"private, no-store"}},"X-Request-Id":{"description":"Request identifier for diagnostics.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or expired user session. Sign in again or refresh your access token.","headers":{"Cache-Control":{"description":"Responses must not be stored.","schema":{"type":"string","const":"private, no-store"}},"X-Request-Id":{"description":"Request identifier for diagnostics.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient tokens or a request origin that is not allowed.","headers":{"Cache-Control":{"description":"Responses must not be stored.","schema":{"type":"string","const":"private, no-store"}},"X-Request-Id":{"description":"Request identifier for diagnostics.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"REQUEST_ALREADY_PROCESSED: this charged operation ID is already recorded. Check your balance before starting a new operation. No response replay.","headers":{"Cache-Control":{"description":"Responses must not be stored.","schema":{"type":"string","const":"private, no-store"}},"X-Request-Id":{"description":"Request identifier for diagnostics.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Request rate exceeded. Wait before retrying.","headers":{"Cache-Control":{"description":"Responses must not be stored.","schema":{"type":"string","const":"private, no-store"}},"X-Request-Id":{"description":"Request identifier for diagnostics.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required service is temporarily unavailable.","headers":{"Cache-Control":{"description":"Responses must not be stored.","schema":{"type":"string","const":"private, no-store"}},"X-Request-Id":{"description":"Request identifier for diagnostics.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"The request timed out. Check the balance before retrying a charged operation.","headers":{"Cache-Control":{"description":"Responses must not be stored.","schema":{"type":"string","const":"private, no-store"}},"X-Request-Id":{"description":"Request identifier for diagnostics.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/tokens":{"get":{"operationId":"getTokenBalance","summary":"Current user token balance","description":"No token charge. Returns only the authenticated user balance.","security":[{"bearerAuth":[]}],"parameters":[{"name":"X-Request-Id","in":"header","required":false,"description":"Optional unique operation ID. Generated when omitted. Reusing an ID already recorded for a charged operation returns 409 REQUEST_ALREADY_PROCESSED; the previous response is not replayed.","schema":{"type":"string","pattern":"^[A-Za-z0-9:_-]{1,128}$","maxLength":128}}],"responses":{"200":{"description":"Success.","headers":{"Cache-Control":{"description":"Responses must not be stored.","schema":{"type":"string","const":"private, no-store"}},"X-Request-Id":{"description":"Request identifier for diagnostics.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenBalanceResponse"}}}},"400":{"description":"Invalid or unsupported input. Correct the request before retrying.","headers":{"Cache-Control":{"description":"Responses must not be stored.","schema":{"type":"string","const":"private, no-store"}},"X-Request-Id":{"description":"Request identifier for diagnostics.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or expired user session. Sign in again or refresh your access token.","headers":{"Cache-Control":{"description":"Responses must not be stored.","schema":{"type":"string","const":"private, no-store"}},"X-Request-Id":{"description":"Request identifier for diagnostics.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient tokens or a request origin that is not allowed.","headers":{"Cache-Control":{"description":"Responses must not be stored.","schema":{"type":"string","const":"private, no-store"}},"X-Request-Id":{"description":"Request identifier for diagnostics.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"REQUEST_ALREADY_PROCESSED: this charged operation ID is already recorded. Check your balance before starting a new operation. No response replay.","headers":{"Cache-Control":{"description":"Responses must not be stored.","schema":{"type":"string","const":"private, no-store"}},"X-Request-Id":{"description":"Request identifier for diagnostics.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Request rate exceeded. Wait before retrying.","headers":{"Cache-Control":{"description":"Responses must not be stored.","schema":{"type":"string","const":"private, no-store"}},"X-Request-Id":{"description":"Request identifier for diagnostics.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A required service is temporarily unavailable.","headers":{"Cache-Control":{"description":"Responses must not be stored.","schema":{"type":"string","const":"private, no-store"}},"X-Request-Id":{"description":"Request identifier for diagnostics.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"The request timed out. Check the balance before retrying a charged operation.","headers":{"Cache-Control":{"description":"Responses must not be stored.","schema":{"type":"string","const":"private, no-store"}},"X-Request-Id":{"description":"Request identifier for diagnostics.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/openapi":{"get":{"operationId":"getOpenApi","summary":"Download this API contract","security":[],"responses":{"200":{"description":"OpenAPI 3.1 JSON document. Public and free.","content":{"application/json":{"schema":{"type":"object","required":["openapi","info","paths"]}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"User access token issued by the platform sign-in. Database credentials and service keys are not API credentials."}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"Pagination":{"type":"object","required":["limit","offset","returned"],"properties":{"limit":{"type":"integer","minimum":0},"offset":{"type":"integer","minimum":0},"returned":{"type":"integer","minimum":0},"total":{"type":"integer","minimum":0},"next_cursor":{"type":["string","null"]}}},"Meta":{"type":"object","required":["endpoint_key","cache","pagination","data_version"],"properties":{"mode":{"type":"string"},"endpoint_key":{"type":"string"},"data_version":{"type":"string"},"cache":{"type":"object","properties":{"hit":{"type":"boolean"},"ttl_seconds":{"type":"integer","minimum":0}}},"pagination":{"$ref":"#/components/schemas/Pagination"}}},"RecordUsage":{"type":"object","required":["tokenUnit","tokensPerRecord","chargedTokens","remainingTokens","returnedRecords","requestId"],"properties":{"tokenUnit":{"const":"record"},"tokensPerRecord":{"const":1},"chargedTokens":{"type":"integer","minimum":0},"remainingTokens":{"type":"integer","minimum":0},"returnedRecords":{"type":"integer","minimum":0},"requestId":{"type":"string"},"idempotent":{"type":"boolean","description":"Legacy field; a duplicate charged operation returns 409 instead of a success response."}}},"Geometry":{"type":["object","null"],"description":"GeoJSON geometry in WGS84. Coordinate positions use longitude, latitude.","properties":{"type":{"type":"string"},"coordinates":{"type":"array","items":{}},"geometries":{"type":"array","items":{"type":"object"}}},"additionalProperties":true},"Project":{"type":"object","properties":{"area_id":{"type":["string","null"]},"area_name":{"type":["string","null"]},"display_area":{"type":["string","null"]},"region":{"type":["string","null"]},"province":{"type":["string","null"]},"comune":{"type":["string","null"]},"quartiere":{"type":["string","null"]},"project_id":{"type":["string","null"]},"source_row_id":{"type":["string","null"]},"project_source":{"type":["string","null"]},"project_source_group":{"type":["string","null"]},"project_name":{"type":["string","null"]},"project_description":{"type":["string","null"]},"project_category_raw":{"type":["string","null"]},"project_macrocategory_code":{"type":["string","null"]},"project_macrocategory":{"type":["string","null"]},"normalized_project_category_code":{"type":["string","null"]},"normalized_project_category":{"type":["string","null"]},"phase":{"type":["string","null"]},"timing_status":{"type":["string","null"]},"project_status":{"type":["string","null"]},"area_intervento":{"type":["string","null"]},"nature_of_investment":{"type":["string","null"]},"lead_entity_name":{"type":["string","null"]},"address":{"type":["string","null"]},"completion_status":{"type":["string","null"]},"geom_type":{"type":["string","null"]},"geometry_source":{"type":["string","null"]},"start_date":{"type":["string","null"]},"finish_date":{"type":["string","null"]},"planned_start_date":{"type":["string","null"]},"actual_start_date":{"type":["string","null"]},"planned_finish_date":{"type":["string","null"]},"actual_finish_date":{"type":["string","null"]},"project_updated_at":{"type":["string","null"]},"start_year":{"type":["integer","null"]},"finish_year":{"type":["integer","null"]},"allocated_funding_eur":{"type":["number","string","null"],"description":"Database decimal values may be JSON strings."},"estimated_cost_eur":{"type":["number","string","null"],"description":"Database decimal values may be JSON strings."},"public_funding_eur":{"type":["number","string","null"],"description":"Database decimal values may be JSON strings."},"pnrr_allocation_eur":{"type":["number","string","null"],"description":"Database decimal values may be JSON strings."},"coesione_payout_eur":{"type":["number","string","null"],"description":"Database decimal values may be JSON strings."},"funding_eur":{"type":["number","string","null"],"description":"Database decimal values may be JSON strings."},"lat":{"type":["number","null"]},"lon":{"type":["number","null"]},"geometry":{"$ref":"#/components/schemas/Geometry"}},"additionalProperties":true},"ProjectsResponse":{"type":"object","required":["data","meta","usage"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Project"}},"meta":{"$ref":"#/components/schemas/Meta"},"usage":{"$ref":"#/components/schemas/RecordUsage"}}},"ProjectFacetsResponse":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","properties":{"regions":{"type":"array","items":{"type":"string"}},"provinces":{"type":"array","items":{"type":"string"}},"comuni":{"type":"array","items":{"type":"string"}},"quartieri":{"type":"array","items":{"type":"string"}},"categories":{"type":"array","items":{"type":"string"}},"microcategories":{"type":"array","items":{"type":"string"}},"project_statuses":{"type":"array","items":{"type":"string"}}}},"meta":{"$ref":"#/components/schemas/Meta"},"usage":{"$ref":"#/components/schemas/RecordUsage"}}},"FundingResponse":{"type":"object","required":["data","meta","usage"],"properties":{"data":{"type":"object","required":["records","series","summary","highlights","area_analysis"],"properties":{"records":{"type":"array","items":{"$ref":"#/components/schemas/Project"}},"series":{"type":"object","properties":{"by_date":{"type":"array","items":{"type":"object","additionalProperties":true}},"by_source":{"type":"array","items":{"type":"object","additionalProperties":true}},"by_category":{"type":"array","items":{"type":"object","additionalProperties":true}}}},"summary":{"type":"object","properties":{"total_records":{"type":"integer","minimum":0},"geocoded_records":{"type":"integer","minimum":0},"finish_year_records":{"type":"integer","minimum":0},"big_project_records":{"type":"integer","minimum":0},"closed_records":{"type":"integer","minimum":0},"active_records":{"type":"integer","minimum":0},"total_funding_eur":{"type":["number","string","null"],"description":"Database decimal values may be JSON strings."},"total_estimated_cost_eur":{"type":["number","string","null"],"description":"Database decimal values may be JSON strings."},"total_pnrr_eur":{"type":["number","string","null"],"description":"Database decimal values may be JSON strings."},"total_coesione_eur":{"type":["number","string","null"],"description":"Database decimal values may be JSON strings."},"big_project_threshold_eur":{"type":["number","string","null"],"description":"Database decimal values may be JSON strings."},"min_date":{"type":["string","null"]},"max_date":{"type":["string","null"]},"timeline_basis":{"type":"string","enum":["start_date","finish_date"]}}},"highlights":{"type":"object","properties":{"recent_project":{"anyOf":[{"$ref":"#/components/schemas/Project"},{"type":"null"}]},"highest_funding_project":{"anyOf":[{"$ref":"#/components/schemas/Project"},{"type":"null"}]},"next_finishing_project":{"anyOf":[{"$ref":"#/components/schemas/Project"},{"type":"null"}]}}},"area_analysis":{"type":"object","description":"Totals for the geographic selection before additional project and date filters.","properties":{"summary":{"type":"object","properties":{"total_records":{"type":"integer","minimum":0},"geocoded_records":{"type":"integer","minimum":0},"finish_year_records":{"type":"integer","minimum":0},"big_project_records":{"type":"integer","minimum":0},"closed_records":{"type":"integer","minimum":0},"active_records":{"type":"integer","minimum":0},"total_funding_eur":{"type":["number","string","null"],"description":"Database decimal values may be JSON strings."},"total_estimated_cost_eur":{"type":["number","string","null"],"description":"Database decimal values may be JSON strings."},"total_pnrr_eur":{"type":["number","string","null"],"description":"Database decimal values may be JSON strings."},"total_coesione_eur":{"type":["number","string","null"],"description":"Database decimal values may be JSON strings."},"big_project_threshold_eur":{"type":["number","string","null"],"description":"Database decimal values may be JSON strings."},"min_date":{"type":["string","null"]},"max_date":{"type":["string","null"]},"timeline_basis":{"type":"string","enum":["start_date","finish_date"]}}},"by_category":{"type":"array","items":{"type":"object","additionalProperties":true}},"highlights":{"type":"object","properties":{"recent_project":{"anyOf":[{"$ref":"#/components/schemas/Project"},{"type":"null"}]},"highest_funding_project":{"anyOf":[{"$ref":"#/components/schemas/Project"},{"type":"null"}]},"next_finishing_project":{"anyOf":[{"$ref":"#/components/schemas/Project"},{"type":"null"}]}}}}}}},"meta":{"$ref":"#/components/schemas/Meta"},"usage":{"$ref":"#/components/schemas/RecordUsage"}}},"TokenBalanceResponse":{"type":"object","required":["authenticated","token_unit","tokens_per_record","tokens_remaining","usage"],"properties":{"authenticated":{"const":true},"token_unit":{"const":"record"},"tokens_per_record":{"const":1},"tokens_remaining":{"type":"integer","minimum":0},"usage":{"type":"object","required":["authenticated","tokenUnit","tokensPerRecord","remainingTokens"],"properties":{"authenticated":{"const":true},"tokenUnit":{"const":"record"},"tokensPerRecord":{"const":1},"remainingTokens":{"type":"integer","minimum":0}}}}},"PredictionInput":{"type":"object","required":["lat","lon","sqm"],"additionalProperties":false,"properties":{"lat":{"type":"number","minimum":-90,"maximum":90},"lon":{"type":"number","minimum":-180,"maximum":180},"sqm":{"type":"number","exclusiveMinimum":0},"address":{"type":"string"},"city":{"type":"string"},"tipologia":{"type":"string","default":"appartamento"},"stato":{"type":"string","default":"buono"},"locali":{"type":["number","null"]},"giardinoMq":{"type":["number","null"]},"terrazzaMq":{"type":["number","null"]},"balconeMq":{"type":["number","null"]},"esposizione":{"type":["string","null"]},"pianotipo":{"type":["string","null"]},"boxAuto":{"type":["string","null"]},"postoAuto":{"type":["string","null"]},"ascensore":{"type":["boolean","null"]},"climatizzazione":{"type":["boolean","null"]},"giardino":{"type":["boolean","null"]},"terrazza":{"type":["boolean","null"]},"balcone":{"type":["boolean","null"]},"cantina":{"type":["boolean","null"]}}},"PredictionResponse":{"type":"object","required":["model_version","price_per_sqm_pred","price_total_pred","usage","tokens_used","tokens_remaining"],"properties":{"model_version":{"type":"string"},"price_per_sqm_pred":{"type":"number"},"price_total_pred":{"type":"number"},"confidence_interval":{"type":"object","properties":{"price_per_sqm":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2},"price_total":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2}}},"contributions_pct":{"type":"object","properties":{"omi":{"type":"number"},"comparables":{"type":"number"},"property_neighborhood":{"type":"number"},"transport":{"type":"number"},"extra":{"type":"number"},"spatial":{"type":"number"}}},"contributions_eur":{"type":"object","properties":{"omi":{"type":"number"},"comparables":{"type":"number"},"property_neighborhood":{"type":"number"},"transport":{"type":"number"},"extra":{"type":"number"},"spatial":{"type":"number"}}},"module_outputs_per_sqm":{"type":"object","properties":{"omi":{"type":"number"},"comparables":{"type":"number"},"property_neighborhood":{"type":"number"},"transport":{"type":"number"},"extra":{"type":"number"},"spatial":{"type":"number"}}},"outlier_score":{"type":"number"},"outlier_flag":{"type":"boolean"},"warnings":{"type":"array","items":{"type":"string"}},"explainability":{"type":"object","properties":{"top_shap_features":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"impact":{"type":"number"}}}},"module_weights":{"type":"object","properties":{"omi":{"type":"number"},"comparables":{"type":"number"},"property_neighborhood":{"type":"number"},"transport":{"type":"number"},"extra":{"type":"number"},"spatial":{"type":"number"}}}}},"future_report_section":{"type":["object","null"],"properties":{"future_price_per_sqm_range":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2},"delta_pct_vs_current":{"type":"number"},"scenario":{"type":"string"},"horizon_year":{"type":"integer"}}},"usage":{"type":"object","required":["tokenUnit","tokensPerEstimation","chargedTokens","remainingTokens","requestId"],"properties":{"tokenUnit":{"const":"estimation"},"tokensPerEstimation":{"const":10},"chargedTokens":{"const":10},"remainingTokens":{"type":"integer","minimum":0},"requestId":{"type":"string"},"idempotent":{"type":"boolean"}}},"tokens_used":{"const":10},"tokens_remaining":{"type":"integer","minimum":0}}}}}}