{"openapi":"3.1.0","info":{"title":"Ospitario agent API","version":"1.10.0","description":"Ospitario is a vacation-rental registry for Italy, Germany, Spain, France and Portugal: one passport per home, with the proof level reached and direct, commission-free contact to the operator. Access to vacation-rental passports for AI assistants and agents: five read-only operations and one inquiry relay (send_inquiry, two steps with an email code). The same operations are MCP tools at https://ospitario.com/mcp. No authentication in phase 1; 60 requests per minute per address here, 60 per session over MCP. Every call is counted per property for the operator's statistics, without personal data of the caller."},"servers":[{"url":"https://ospitario.com"}],"paths":{"/api/v1/search":{"get":{"operationId":"search_properties","summary":"Search vacation rentals","description":"Find vacation rentals in a municipality or region (Italy, Germany, Spain, France, Portugal) for a number of guests. Where: municipality, province, (Italy) region, or a radius around an Italian municipality (near) or a point (latitude/longitude), each hit with its straight-line distance; the order stays tier, then name, sort by distance yourself. Criteria: capacity, bedrooms, bathrooms, amenities (a fixed table of names incl. pool facets such as private or heated, otherwise exact), what is rented, pets allowed, highest indicative price and, with from/to, dates not blocked in the operator's synced calendar. A stated fact that contradicts a criterion always leaves the property out. Each hit lists the criteria a stated fact meets in matched and says match (every criterion met) or possible, with the open points in unknown: by default only availability on request and a heated pool's heating on the requested dates; with include_possible also any fact the operator did not state (no current calendar is never read as free). Ask the operator about every point in unknown before relying on it. At most 20 results, ordered by the strongest free tier, then name (with include_possible matches first); the paid tier L5 does not change the order. No ranking by anything else, no fuzzy matching. Each result has priceFrom (indicative, negotiated directly, no booking) and the next window not blocked in the operator's calendar. Availability is a hint, never a booking commitment: a night not blocked in the operator's synced calendar may already be taken, since the calendar is a copy that can lag behind; only the operator confirms availability, and Ospitario holds or books nothing. Prices are indicative, stated by the host (on an unclaimed passport: taken from the official website), negotiated directly with the host; there is no booking through Ospitario. Every result is a property with a proven listing (L2/L2c), a verified operator (L3), a right to manage verified by document review (LA) or, marked L0 and unclaimed, facts from the operator's official website with nothing proven; the result names the tier and the date it was reached, and whether the registration number (Italy: CIN) was checked against the public register. Contact is direct with the operator and commission-free, so the traveler pays no platform fee. No result means nothing proven matches; nothing is inferred, estimated or filled in.","parameters":[{"name":"country","in":"query","required":false,"description":"ISO 3166-1 alpha-2 country code: IT, DE, ES, FR or PT","schema":{"description":"ISO 3166-1 alpha-2 country code: IT, DE, ES, FR or PT","type":"string","enum":["IT","DE","ES","FR","PT"]}},{"name":"municipality","in":"query","required":false,"description":"Exact municipality name, e.g. Lecce","schema":{"description":"Exact municipality name, e.g. Lecce","type":"string","minLength":2,"maxLength":80}},{"name":"province","in":"query","required":false,"description":"Region code within the country, ISO 3166-2 without the prefix: IT/ES province (LE), FR département (75), DE Land (HH), PT distrito (11)","schema":{"description":"Region code within the country, ISO 3166-2 without the prefix: IT/ES province (LE), FR département (75), DE Land (HH), PT distrito (11)","type":"string","minLength":1,"maxLength":3}},{"name":"region","in":"query","required":false,"description":"Italian region, by its Italian name or slug (Abruzzo, Basilicata, Calabria, Campania, Emilia-Romagna, Friuli-Venezia Giulia, Lazio, Liguria, Lombardia, Marche, Molise, Piemonte, Puglia, Sardegna, Sicilia, Toscana, Trentino-Alto Adige, Umbria, Valle d’Aosta, Veneto); the usual English, German, French, Spanish and Portuguese names are understood too (Apulia, Toskana). Italy only; matches the passport's province","schema":{"description":"Italian region, by its Italian name or slug (Abruzzo, Basilicata, Calabria, Campania, Emilia-Romagna, Friuli-Venezia Giulia, Lazio, Liguria, Lombardia, Marche, Molise, Piemonte, Puglia, Sardegna, Sicilia, Toscana, Trentino-Alto Adige, Umbria, Valle d’Aosta, Veneto); the usual English, German, French, Spanish and Portuguese names are understood too (Apulia, Toskana). Italy only; matches the passport's province","type":"string","minLength":2,"maxLength":40}},{"name":"near","in":"query","required":false,"description":"Italian municipality to search around, by name (e.g. Lecce); with radiusKm. A name several municipalities carry needs nearProvince","schema":{"description":"Italian municipality to search around, by name (e.g. Lecce); with radiusKm. A name several municipalities carry needs nearProvince","type":"string","minLength":2,"maxLength":80}},{"name":"nearProvince","in":"query","required":false,"description":"Province code of near when the name is ambiguous (e.g. LE)","schema":{"description":"Province code of near when the name is ambiguous (e.g. LE)","type":"string","minLength":2,"maxLength":2}},{"name":"latitude","in":"query","required":false,"description":"Point to search around, WGS 84 degrees; with longitude and radiusKm, instead of near","schema":{"description":"Point to search around, WGS 84 degrees; with longitude and radiusKm, instead of near","type":"number","minimum":-90,"maximum":90}},{"name":"longitude","in":"query","required":false,"description":"Point to search around, WGS 84 degrees; with latitude","schema":{"description":"Point to search around, WGS 84 degrees; with latitude","type":"number","minimum":-180,"maximum":180}},{"name":"radiusKm","in":"query","required":false,"description":"Radius around near or latitude/longitude in km, straight line, default 20. A passport counts at its published exact location, else at its municipality's centre (computed from Istat's boundaries), so a home just inside a municipality can lie a few km off; every hit names its distance and basis. Municipality centres computed by Ospitario from Istat, Confini delle unità amministrative a fini statistici al 1° gennaio 2026 (CC BY 4.0)","schema":{"description":"Radius around near or latitude/longitude in km, straight line, default 20. A passport counts at its published exact location, else at its municipality's centre (computed from Istat's boundaries), so a home just inside a municipality can lie a few km off; every hit names its distance and basis. Municipality centres computed by Ospitario from Istat, Confini delle unità amministrative a fini statistici al 1° gennaio 2026 (CC BY 4.0)","type":"integer","minimum":1,"maximum":100}},{"name":"guests","in":"query","required":true,"description":"Number of guests; properties with a lower capacity are left out","schema":{"description":"Number of guests; properties with a lower capacity are left out","type":"integer","minimum":1,"maximum":50}},{"name":"from","in":"query","required":false,"description":"Check-in date YYYY-MM-DD; requires to","schema":{"description":"Check-in date YYYY-MM-DD; requires to","type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"to","in":"query","required":false,"description":"Checkout date YYYY-MM-DD; requires from","schema":{"description":"Checkout date YYYY-MM-DD; requires from","type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"bedrooms","in":"query","required":false,"description":"Minimum number of bedrooms","schema":{"description":"Minimum number of bedrooms","type":"integer","minimum":0,"maximum":30}},{"name":"bathrooms","in":"query","required":false,"description":"Minimum number of bathrooms; a half bath counts 0.5","schema":{"description":"Minimum number of bathrooms; a half bath counts 0.5","type":"number","minimum":0,"maximum":20,"multipleOf":0.5}},{"name":"amenities","in":"query","required":false,"description":"Every listed amenity must be present. These names match the operator's wording in any of the six languages through a fixed table: pool, wifi, parking, airConditioning (ac), garden, seaView, terrace, kitchen, washingMachine (washerDryer), bbq (outdoorGrill), heating, fireplace, balcony, tv, hotTub, elevator, crib, microwave, workspace. A pool can be asked with its facets: \"private pool\", \"shared pool\", \"heated pool\", \"indoor pool\", \"outdoor pool\" (or the same words in Italian, German, Spanish, Portuguese, French); a facet the operator did not state is unknown, not a match. Any other word must match an amenity exactly (case-insensitive).","schema":{"description":"Every listed amenity must be present. These names match the operator's wording in any of the six languages through a fixed table: pool, wifi, parking, airConditioning (ac), garden, seaView, terrace, kitchen, washingMachine (washerDryer), bbq (outdoorGrill), heating, fireplace, balcony, tv, hotTub, elevator, crib, microwave, workspace. A pool can be asked with its facets: \"private pool\", \"shared pool\", \"heated pool\", \"indoor pool\", \"outdoor pool\" (or the same words in Italian, German, Spanish, Portuguese, French); a facet the operator did not state is unknown, not a match. Any other word must match an amenity exactly (case-insensitive).","maxItems":20,"type":"array","items":{"type":"string","minLength":1,"maxLength":60}},"style":"form","explode":true},{"name":"placeKind","in":"query","required":false,"description":"entire, private_room or shared_room; properties that did not state it are left out","schema":{"description":"entire, private_room or shared_room; properties that did not state it are left out","type":"string","enum":["entire","private_room","shared_room"]}},{"name":"propertyKind","in":"query","required":false,"description":"Kind of building: apartment, house, villa, farmhouse, trullo, cottage, chalet, other; a property that did not state it is open (unknown: propertyKind), another kind leaves it out","schema":{"description":"Kind of building: apartment, house, villa, farmhouse, trullo, cottage, chalet, other; a property that did not state it is open (unknown: propertyKind), another kind leaves it out","type":"string","enum":["apartment","house","villa","farmhouse","trullo","cottage","chalet","other"]}},{"name":"pets","in":"query","required":false,"description":"true: only properties whose operator states that pets are allowed","schema":{"description":"true: only properties whose operator states that pets are allowed","type":"boolean","const":true}},{"name":"children","in":"query","required":false,"description":"true: only properties whose operator states that children are welcome","schema":{"description":"true: only properties whose operator states that children are welcome","type":"boolean","const":true}},{"name":"stepFree","in":"query","required":false,"description":"true: only properties whose operator states step-free access","schema":{"description":"true: only properties whose operator states step-free access","type":"boolean","const":true}},{"name":"maxPrice","in":"query","required":false,"description":"Highest indicative price per night in EUR: properties whose lowest current or future priceFrom is above it, or that gave no price, are left out","schema":{"description":"Highest indicative price per night in EUR: properties whose lowest current or future priceFrom is above it, or that gave no price, are left out","type":"integer","minimum":1,"maximum":100000}},{"name":"include_possible","in":"query","required":false,"description":"true: also return possible matches, where a requested fact is not stated (capacity, bedrooms, an amenity or pool facet, pets, price, current calendar) and nothing stated contradicts the request; each hit names the open points in unknown. Default false: only hits that meet every criterion, plus availability on request.","schema":{"description":"true: also return possible matches, where a requested fact is not stated (capacity, bedrooms, an amenity or pool facet, pets, price, current calendar) and nothing stated contradicts the request; each hit names the open points in unknown. Default false: only hits that meet every criterion, plus availability on request.","type":"boolean"}},{"name":"lang","in":"query","required":false,"description":"Language of labels in the result; defaults to en","schema":{"description":"Language of labels in the result; defaults to en","type":"string","enum":["it","de","en","es","pt","fr"]}}],"responses":{"200":{"description":"Result; an empty list or found:false is an honest not-found","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"municipality":{"type":"string"},"province":{"description":"Region code, ISO 3166-2 without the country prefix: IT/ES province (LE, GR), FR département (75), DE Land (HH), PT distrito (11)","anyOf":[{"type":"string"},{"type":"null"}]},"type":{"description":"Accommodation type as stated by the operator","type":"string"},"capacity":{"description":"Maximum number of guests","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"bedrooms":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"amenities":{"description":"Amenities in the operator's own words","type":"array","items":{"type":"string"}},"placeKind":{"description":"What the guest rents: the entire place, a private room or a shared room. Declared by the operator; null: not stated.","anyOf":[{"type":"string","enum":["entire","private_room","shared_room"]},{"type":"null"}]},"petsAllowed":{"description":"Whether pets are allowed, as the operator states it; null: not stated, ask the operator.","anyOf":[{"type":"boolean"},{"type":"null"}]},"availability":{"type":"object","properties":{"status":{"description":"calendar: blocked dates come from the operator's calendar, synced recently (lastSync); unblocked nights are not confirmed free; on_request: the operator answers availability on request, no dates are published; unknown: no current calendar, ask the operator. Availability is a hint, never a booking commitment: a night not blocked in the operator's synced calendar may already be taken, since the calendar is a copy that can lag behind; only the operator confirms availability, and Ospitario holds or books nothing.","type":"string","enum":["calendar","on_request","unknown"]},"lastSync":{"description":"Last successful calendar sync, ISO timestamp","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["status","lastSync"],"additionalProperties":false},"priceFrom":{"anyOf":[{"description":"Indicative price per night. Prices are indicative, stated by the host (on an unclaimed passport: taken from the official website), negotiated directly with the host; there is no booking through Ospitario. null: the operator gave no price.","type":"object","properties":{"nightlyFrom":{"description":"Lowest nightly price among the current and future periods","type":"number"},"currency":{"type":"string","enum":["EUR"]},"label":{"description":"e.g. \"da 120 €/notte\"","type":"string"},"seasons":{"description":"Current and future periods; ended ones are left out","type":"array","items":{"type":"object","properties":{"nightlyFrom":{"description":"Lowest nightly price the operator states for this period","type":"number"},"currency":{"type":"string","enum":["EUR"]},"seasonLabel":{"description":"Season name in the operator's words","anyOf":[{"type":"string"},{"type":"null"}]},"validFrom":{"description":"First day of the period, YYYY-MM-DD; null: no start given","anyOf":[{"type":"string"},{"type":"null"}]},"validTo":{"description":"Last day of the period, YYYY-MM-DD; null: no end given","anyOf":[{"type":"string"},{"type":"null"}]},"label":{"type":"string"}},"required":["nightlyFrom","currency","seasonLabel","validFrom","validTo","label"],"additionalProperties":false}},"updatedAt":{"description":"When the operator last changed the prices, YYYY-MM-DD","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["nightlyFrom","currency","label","seasons","updatedAt"],"additionalProperties":false},{"type":"null"}]},"unclaimed":{"description":"true: an unclaimed passport (tier L0) built from the operator's official website; email and phone are not shown, write with send_inquiry","type":"boolean"},"country":{"description":"ISO 3166-1 alpha-2 country code","type":"string"},"pool":{"description":"The pool, facet by facet; null: not stated. Never inferred.","type":"object","properties":{"present":{"description":"true: the operator declares a pool, or a line names a pool of the house; false: declared or stated absent; null: not stated","anyOf":[{"type":"boolean"},{"type":"null"}]},"access":{"description":"null: not stated, or the lines disagree","anyOf":[{"type":"string","enum":["private","shared"]},{"type":"null"}]},"setting":{"description":"null: not stated","anyOf":[{"type":"string","enum":["indoor","outdoor"]},{"type":"null"}]},"heated":{"description":"true: a heated or heatable pool. It does not say the pool is heated on given dates: see heatedSeason and heating. null: not stated","anyOf":[{"type":"boolean"},{"type":"null"}]},"heating":{"description":"As the operator declares it: no heating, heating included, heating for a surcharge, heating on request (notice in notes); null: not declared","anyOf":[{"type":"string","enum":["none","included","surcharge","on_request"]},{"type":"null"}]},"season":{"description":"Days the pool is open every year, MM-DD to MM-DD inclusive (may run across New Year); null when several periods are declared (see seasons); null: not declared, ask the operator","anyOf":[{"type":"object","properties":{"from":{"description":"MM-DD","type":"string"},"until":{"description":"MM-DD, inclusive","type":"string"}},"required":["from","until"],"additionalProperties":false},{"type":"null"}]},"heatedSeason":{"description":"Days the pool is heated every year, MM-DD to MM-DD; null: not declared, or several periods (see heatedSeasons)","anyOf":[{"type":"object","properties":{"from":{"description":"MM-DD","type":"string"},"until":{"description":"MM-DD, inclusive","type":"string"}},"required":["from","until"],"additionalProperties":false},{"type":"null"}]},"seasons":{"description":"Every period the pool is open each year, as the operator declares them; empty: not declared, ask the operator","type":"array","items":{"type":"object","properties":{"from":{"description":"MM-DD","type":"string"},"until":{"description":"MM-DD, inclusive","type":"string"}},"required":["from","until"],"additionalProperties":false}},"heatedSeasons":{"description":"Every period the pool is heated each year; empty: not declared","type":"array","items":{"type":"object","properties":{"from":{"description":"MM-DD","type":"string"},"until":{"description":"MM-DD, inclusive","type":"string"}},"required":["from","until"],"additionalProperties":false}},"notes":{"description":"Conditions in the operator's words: surcharge, notice for heating, hours, age rules","anyOf":[{"type":"string"},{"type":"null"}]},"source":{"description":"operator: declared in the passport's pool fields; amenity_text: read from the amenity lines by fixed patterns in six languages, a line that places the pool elsewhere (public, nearby) does not count; null: nothing about a pool","anyOf":[{"type":"string","enum":["operator","amenity_text"]},{"type":"null"}]}},"required":["present","access","setting","heated","heating","season","heatedSeason","seasons","heatedSeasons","notes","source"],"additionalProperties":false},"minNights":{"description":"Minimum stay in nights as the operator states it; null: not stated, ask the operator","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"childrenAllowed":{"description":"Whether children are welcome, as the operator states it; null: not stated","anyOf":[{"type":"boolean"},{"type":"null"}]},"stepFreeAccess":{"description":"Whether the home can be entered without steps, as the operator states it; null: not stated. Not an accessibility certification","anyOf":[{"type":"boolean"},{"type":"null"}]},"bathrooms":{"description":"Bathrooms; a half bath counts 0.5. null: not stated.","anyOf":[{"type":"number"},{"type":"null"}]},"booking":{"description":"What a traveler can do with this passport: contact the operator, never book through Ospitario. Availability is separate (availability, blocked)","type":"object","properties":{"bookable":{"description":"Always false: Ospitario takes no bookings and no payment. A result, a free night or a sent inquiry reserves nothing; the operator confirms dates and price","type":"boolean","const":false},"contact":{"description":"direct: the operator's own channels are in contact, and send_inquiry mails the operator; relay_only: unclaimed, write with send_inquiry (the official website in contact.site is the operator's own page, not an inquiry channel of Ospitario). send_inquiry may still refuse, with a reason","type":"string","enum":["direct","relay_only"]}},"required":["bookable","contact"],"additionalProperties":false},"match":{"description":"match: every criterion is met by a stated fact; possible: nothing stated contradicts the request, but the points in unknown are open. Properties that contradict a criterion are never returned","type":"string","enum":["match","possible"]},"matched":{"description":"Criteria of this request that a stated fact meets, named as in unknown: country, municipality, province, region, near (within radiusKm), guests, bedrooms, bathrooms, an amenity word as asked, \"pool open on the requested dates\", \"pool heating on the requested dates\", placeKind, pets, children, stepFree, minNights, price, availability (free in a current calendar). Computed from the passport's data, never generated","type":"array","items":{"type":"string"}},"unknown":{"description":"Criteria no stated fact settles, e.g. guests, bedrooms, availability, pets, price, an amenity word, \"pool heating on the requested dates\"; ask the operator about these before relying on them","type":"array","items":{"type":"string"}},"verification":{"type":"object","properties":{"tier":{"description":"Verification tier (docs: ADR 0012, 0017, 0024, 0025). L0 unclaimed: facts read from the operator's official website, nothing proven, the operator has not claimed the page; contact only through send_inquiry. L2 listing verified: the operator proved control of the platform listing (calendar export link with the listing id, platform email with a valid DKIM signature, or channel manager); since 2026-11-07 also their right to manage the property (LA or L3), and earlier L2 stands as it was reached. L2c listing calendar proven (Booking, Vrbo): the operator blocked a random date Ospitario named in that platform's calendar export within 48 hours; no new L2c since 2026-11-07. LA right to manage verified (document review): Ospitario's admin checked documents tying the operator to this property (registration record, deed, lease, mandate or company register); a person found them consistent, without eID, so it does not prove who holds the account and never proves a platform listing. L3 operator verified: the operator's eID identity (SPID/CIE) matches the CIN holder in the national register's PDF. L4 document verified (automated check): an ownership, lease or mandate document is consistent with that identity and the property; it states consistency, not authenticity. L5 manually verified: a reviewer checked the document (an optional upgrade; it does not affect search order).","type":"string","enum":["L0","L2","L2c","LA","L3","L4","L5"]},"label":{"description":"Human-readable name of the tier","type":"string"},"date":{"description":"Date the tier was reached, YYYY-MM-DD","type":"string"}},"required":["tier","label","date"],"additionalProperties":false},"distance":{"description":"From the requested point (near: that municipality's centre) to the passport; null without near or latitude/longitude","anyOf":[{"type":"object","properties":{"km":{"description":"Straight-line distance in whole km; not a driving distance","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"from":{"description":"location: the exact location the operator published; municipality_centre: the centre of the passport's municipality (Istat boundaries), the home itself may lie a few km off","type":"string","enum":["location","municipality_centre"]}},"required":["km","from"],"additionalProperties":false},{"type":"null"}]},"nextFreeWindow":{"description":"First span not blocked in the operator's synced calendar from the requested check-in (or today) that is at least as long as the requested stay; null when the calendar is not current or on request. Not a booking commitment: ask the operator to confirm.","anyOf":[{"type":"object","properties":{"from":{"description":"First free night, YYYY-MM-DD","type":"string"},"to":{"description":"Checkout day when the next blocked night begins, YYYY-MM-DD; null: free to the end of the calendar horizon","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["from","to"],"additionalProperties":false},{"type":"null"}]},"contactPageUrl":{"description":"Page with the passport and the operator's direct contact; give this link to the traveler","type":"string"}},"required":["slug","name","municipality","province","type","capacity","bedrooms","amenities","placeKind","petsAllowed","availability","priceFrom","unclaimed","country","pool","minNights","childrenAllowed","stepFreeAccess","bathrooms","booking","match","matched","unknown","verification","distance","nextFreeWindow","contactPageUrl"],"additionalProperties":false}}},"required":["results"],"additionalProperties":false}}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"issues":{"type":"array"}}}}}},"429":{"description":"More than 60 requests per minute from this client; see Retry-After"}}}},"/api/v1/lookup/url":{"get":{"operationId":"lookup_by_url","summary":"Look up a listing link","description":"Resolve a listing link (Airbnb, Booking, Vrbo) to the operator's Ospitario passport, e.g. when a traveler wants to book a place they know directly. Exact match on the listing's own L2/L2c proof or found:false; never a list; a property verified only as an operator (L3) or an unclaimed passport (L0) is never returned for a link. The link is only parsed, never opened. Insurance status and safety equipment are host-declared, not verified: Ospitario has seen no policy and no device. Every result is a property with a proven listing (L2/L2c), a verified operator (L3), a right to manage verified by document review (LA) or, marked L0 and unclaimed, facts from the operator's official website with nothing proven; the result names the tier and the date it was reached, and whether the registration number (Italy: CIN) was checked against the public register. Contact is direct with the operator and commission-free, so the traveler pays no platform fee. No result means nothing proven matches; nothing is inferred, estimated or filled in.","parameters":[{"name":"url","in":"query","required":true,"description":"Link to a listing on Airbnb, Booking or Vrbo","schema":{"description":"Link to a listing on Airbnb, Booking or Vrbo","type":"string","minLength":10,"maxLength":2000}},{"name":"lang","in":"query","required":false,"description":"Language of labels in the result; defaults to en","schema":{"description":"Language of labels in the result; defaults to en","type":"string","enum":["it","de","en","es","pt","fr"]}}],"responses":{"200":{"description":"Result; an empty list or found:false is an honest not-found","content":{"application/json":{"schema":{"type":"object","properties":{"found":{"type":"boolean"},"reason":{"description":"not_found: no operator holds a listing-control proof (L2/L2c) on this listing; unsupported_url: not a listing link Ospitario understands","type":"string","enum":["not_found","unsupported_url"]},"property":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"municipality":{"type":"string"},"province":{"description":"Region code, ISO 3166-2 without the country prefix: IT/ES province (LE, GR), FR département (75), DE Land (HH), PT distrito (11)","anyOf":[{"type":"string"},{"type":"null"}]},"country":{"description":"ISO 3166-1 alpha-2 country code","type":"string"},"type":{"description":"Accommodation type as stated by the operator","type":"string"},"capacity":{"description":"Maximum number of guests","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"bedrooms":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"amenities":{"description":"Amenities in the operator's own words","type":"array","items":{"type":"string"}},"pool":{"description":"The pool, facet by facet; null: not stated. Never inferred.","type":"object","properties":{"present":{"description":"true: the operator declares a pool, or a line names a pool of the house; false: declared or stated absent; null: not stated","anyOf":[{"type":"boolean"},{"type":"null"}]},"access":{"description":"null: not stated, or the lines disagree","anyOf":[{"type":"string","enum":["private","shared"]},{"type":"null"}]},"setting":{"description":"null: not stated","anyOf":[{"type":"string","enum":["indoor","outdoor"]},{"type":"null"}]},"heated":{"description":"true: a heated or heatable pool. It does not say the pool is heated on given dates: see heatedSeason and heating. null: not stated","anyOf":[{"type":"boolean"},{"type":"null"}]},"heating":{"description":"As the operator declares it: no heating, heating included, heating for a surcharge, heating on request (notice in notes); null: not declared","anyOf":[{"type":"string","enum":["none","included","surcharge","on_request"]},{"type":"null"}]},"season":{"description":"Days the pool is open every year, MM-DD to MM-DD inclusive (may run across New Year); null when several periods are declared (see seasons); null: not declared, ask the operator","anyOf":[{"type":"object","properties":{"from":{"description":"MM-DD","type":"string"},"until":{"description":"MM-DD, inclusive","type":"string"}},"required":["from","until"],"additionalProperties":false},{"type":"null"}]},"heatedSeason":{"description":"Days the pool is heated every year, MM-DD to MM-DD; null: not declared, or several periods (see heatedSeasons)","anyOf":[{"type":"object","properties":{"from":{"description":"MM-DD","type":"string"},"until":{"description":"MM-DD, inclusive","type":"string"}},"required":["from","until"],"additionalProperties":false},{"type":"null"}]},"seasons":{"description":"Every period the pool is open each year, as the operator declares them; empty: not declared, ask the operator","type":"array","items":{"type":"object","properties":{"from":{"description":"MM-DD","type":"string"},"until":{"description":"MM-DD, inclusive","type":"string"}},"required":["from","until"],"additionalProperties":false}},"heatedSeasons":{"description":"Every period the pool is heated each year; empty: not declared","type":"array","items":{"type":"object","properties":{"from":{"description":"MM-DD","type":"string"},"until":{"description":"MM-DD, inclusive","type":"string"}},"required":["from","until"],"additionalProperties":false}},"notes":{"description":"Conditions in the operator's words: surcharge, notice for heating, hours, age rules","anyOf":[{"type":"string"},{"type":"null"}]},"source":{"description":"operator: declared in the passport's pool fields; amenity_text: read from the amenity lines by fixed patterns in six languages, a line that places the pool elsewhere (public, nearby) does not count; null: nothing about a pool","anyOf":[{"type":"string","enum":["operator","amenity_text"]},{"type":"null"}]}},"required":["present","access","setting","heated","heating","season","heatedSeason","seasons","heatedSeasons","notes","source"],"additionalProperties":false},"placeKind":{"description":"What the guest rents: the entire place, a private room or a shared room. Declared by the operator; null: not stated.","anyOf":[{"type":"string","enum":["entire","private_room","shared_room"]},{"type":"null"}]},"bathrooms":{"description":"Bathrooms; a half bath counts 0.5. null: not stated.","anyOf":[{"type":"number"},{"type":"null"}]},"petsAllowed":{"description":"Whether pets are allowed, as the operator states it; null: not stated, ask the operator.","anyOf":[{"type":"boolean"},{"type":"null"}]},"checkinFrom":{"description":"Check-in from, HH:MM local time; null: not stated","anyOf":[{"type":"string"},{"type":"null"}]},"checkoutUntil":{"description":"Checkout until, HH:MM local time; null: not stated","anyOf":[{"type":"string"},{"type":"null"}]},"location":{"description":"Exact location and address, only when the operator chose to publish them; never for an unclaimed passport","anyOf":[{"type":"object","properties":{"latitude":{"type":"number"},"longitude":{"type":"number"},"streetAddress":{"anyOf":[{"type":"string"},{"type":"null"}]},"postalCode":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["latitude","longitude","streetAddress","postalCode"],"additionalProperties":false},{"type":"null"}]},"minNights":{"description":"Minimum stay in nights as the operator states it; null: not stated, ask the operator","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"beds":{"description":"Beds by kind as the operator states them; null: not stated","anyOf":[{"type":"object","properties":{"double":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"single":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"sofa":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"bunk":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["double","single","sofa","bunk"],"additionalProperties":false},{"type":"null"}]},"extraCosts":{"description":"Costs beyond the nightly price in the operator's words (cleaning, tourist tax, linen, energy); null: not stated, which is not the same as none","anyOf":[{"type":"string"},{"type":"null"}]},"childrenAllowed":{"description":"Whether children are welcome, as the operator states it; null: not stated","anyOf":[{"type":"boolean"},{"type":"null"}]},"stepFreeAccess":{"description":"Whether the home can be entered without steps, as the operator states it; null: not stated. Not an accessibility certification","anyOf":[{"type":"boolean"},{"type":"null"}]},"unitCount":{"description":"Separately rentable homes this passport describes; 1: one home; more: ask the operator which unit the facts are for; null: not stated","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"propertyKind":{"description":"Kind of building from a fixed list (farmhouse: masseria, casale; trullo: Apulian trullo); type keeps the operator's own word. null: not stated","anyOf":[{"type":"string","enum":["apartment","house","villa","farmhouse","trullo","cottage","chalet","other"]},{"type":"null"}]},"smokingAllowed":{"description":"Whether smoking is allowed inside, as the operator states it; null: not stated","anyOf":[{"type":"boolean"},{"type":"null"}]},"eventsAllowed":{"description":"Whether parties or events are allowed, as the operator states it; null: not stated","anyOf":[{"type":"boolean"},{"type":"null"}]},"cleaningFee":{"description":"Cleaning fee per stay as the operator states it; null: not stated (which is not the same as none; see extraCosts)","anyOf":[{"type":"object","properties":{"amount":{"description":"Per stay, as stated; 0: none","type":"number"},"currency":{"type":"string","const":"EUR"}},"required":["amount","currency"],"additionalProperties":false},{"type":"null"}]},"securityDeposit":{"description":"Security deposit per stay as the operator states it; null: not stated","anyOf":[{"type":"object","properties":{"amount":{"description":"Per stay, as stated; 0: none","type":"number"},"currency":{"type":"string","const":"EUR"}},"required":["amount","currency"],"additionalProperties":false},{"type":"null"}]},"facilities":{"description":"true: there, false: stated absent, null: not stated. The operator's yes/no wins; otherwise read from the amenity lines by fixed patterns, as for the pool","type":"object","properties":{"parking":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"workspace":{"description":"A place to work (desk); not a statement about the internet speed","anyOf":[{"type":"boolean"},{"type":"null"}]},"airConditioning":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"heating":{"anyOf":[{"type":"boolean"},{"type":"null"}]}},"required":["parking","workspace","airConditioning","heating"],"additionalProperties":false},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"locationNotes":{"anyOf":[{"type":"string"},{"type":"null"}]},"houseRules":{"anyOf":[{"type":"string"},{"type":"null"}]},"cancellation":{"anyOf":[{"type":"string"},{"type":"null"}]},"contact":{"description":"Direct contact of the operator; no commission and no intermediary","type":"object","properties":{"phone":{"anyOf":[{"type":"string"},{"type":"null"}]},"whatsapp":{"anyOf":[{"type":"string"},{"type":"null"}]},"email":{"anyOf":[{"type":"string"},{"type":"null"}]},"site":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["phone","whatsapp","email","site"],"additionalProperties":false},"verification":{"description":"Strongest current tier of the property and its listings","anyOf":[{"type":"object","properties":{"tier":{"description":"Verification tier (docs: ADR 0012, 0017, 0024, 0025). L0 unclaimed: facts read from the operator's official website, nothing proven, the operator has not claimed the page; contact only through send_inquiry. L2 listing verified: the operator proved control of the platform listing (calendar export link with the listing id, platform email with a valid DKIM signature, or channel manager); since 2026-11-07 also their right to manage the property (LA or L3), and earlier L2 stands as it was reached. L2c listing calendar proven (Booking, Vrbo): the operator blocked a random date Ospitario named in that platform's calendar export within 48 hours; no new L2c since 2026-11-07. LA right to manage verified (document review): Ospitario's admin checked documents tying the operator to this property (registration record, deed, lease, mandate or company register); a person found them consistent, without eID, so it does not prove who holds the account and never proves a platform listing. L3 operator verified: the operator's eID identity (SPID/CIE) matches the CIN holder in the national register's PDF. L4 document verified (automated check): an ownership, lease or mandate document is consistent with that identity and the property; it states consistency, not authenticity. L5 manually verified: a reviewer checked the document (an optional upgrade; it does not affect search order).","type":"string","enum":["L0","L2","L2c","LA","L3","L4","L5"]},"label":{"description":"Human-readable name of the tier","type":"string"},"date":{"description":"Date the tier was reached, YYYY-MM-DD","type":"string"}},"required":["tier","label","date"],"additionalProperties":false},{"type":"null"}]},"registration":{"description":"Registration number status; null if the operator gave none","anyOf":[{"type":"object","properties":{"number":{"description":"The registration number as the operator declared it (Italy: CIN); checked only as far as status says","type":"string"},"status":{"description":"unchecked: the operator declared the country's short-term rental registration number (Italy: CIN), not yet checked against the public register; exists: the number is in the register; missing: the register no longer lists it.","type":"string","enum":["unchecked","exists","missing"]},"label":{"type":"string"},"checkedAt":{"description":"Day the number was last found in the official source (YYYY-MM-DD); a match of the code, never a check of the operator's identity","anyOf":[{"type":"string"},{"type":"null"}]},"source":{"description":"The official source that confirmed the number, with its licence; null when none did","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["number","status","label","checkedAt","source"],"additionalProperties":false},{"type":"null"}]},"references":{"description":"Platform listings proven to belong to this operator, each with its own tier, date and passed proofs","type":"array","items":{"type":"object","properties":{"domain":{"type":"string"},"listingId":{"description":"The platform's own listing id (Booking: country/slug)","type":"string"},"tier":{"type":"string","enum":["L2","L2c"]},"label":{"type":"string"},"date":{"type":"string"},"proofs":{"description":"Passed proofs only, with method and date","type":"array","items":{"type":"object","properties":{"method":{"description":"How listing control was proven. airbnb_calendar: the operator's Airbnb calendar export link carries the listing id; date_challenge: Ospitario named a random date, and the operator blocked it in the platform's calendar export within 48 hours (not used for new proofs since 2026-11-07); platform_email: a platform email to the operator with a valid DKIM signature; channel_manager: the operator's channel manager lists the listing.","type":"string","enum":["airbnb_calendar","date_challenge","platform_email","channel_manager"]},"label":{"type":"string"},"date":{"description":"Last passed check, YYYY-MM-DD","type":"string"}},"required":["method","label","date"],"additionalProperties":false}}},"required":["domain","listingId","tier","label","date","proofs"],"additionalProperties":false}},"availability":{"type":"object","properties":{"status":{"description":"calendar: blocked dates come from the operator's calendar, synced recently (lastSync); unblocked nights are not confirmed free; on_request: the operator answers availability on request, no dates are published; unknown: no current calendar, ask the operator. Availability is a hint, never a booking commitment: a night not blocked in the operator's synced calendar may already be taken, since the calendar is a copy that can lag behind; only the operator confirms availability, and Ospitario holds or books nothing.","type":"string","enum":["calendar","on_request","unknown"]},"lastSync":{"description":"Last successful calendar sync, ISO timestamp","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["status","lastSync"],"additionalProperties":false},"blocked":{"description":"Blocked date ranges from the operator's calendar as last synced; a night not listed is not confirmed free","type":"array","items":{"type":"object","properties":{"from":{"description":"First blocked night, YYYY-MM-DD","type":"string"},"to":{"description":"Checkout day, YYYY-MM-DD (exclusive)","type":"string"}},"required":["from","to"],"additionalProperties":false}},"liabilityInsurance":{"anyOf":[{"description":"Liability insurance (RC). Insurance status and safety equipment are host-declared, not verified: Ospitario has seen no policy and no device. null: the operator said nothing. The traveler should ask the operator for the policy before booking; platform guarantees (e.g. AirCover) do not cover direct bookings.","type":"object","properties":{"status":{"description":"declared: the operator states a liability insurance (RC) policy; none: the operator states there is none","type":"string","enum":["declared","none"]},"insurer":{"description":"Insurer as named by the operator","anyOf":[{"type":"string"},{"type":"null"}]},"validUntil":{"description":"End of the policy as stated by the operator, YYYY-MM-DD","anyOf":[{"type":"string"},{"type":"null"}]},"label":{"type":"string"}},"required":["status","insurer","validUntil","label"],"additionalProperties":false},{"type":"null"}]},"priceFrom":{"anyOf":[{"description":"Indicative price per night. Prices are indicative, stated by the host (on an unclaimed passport: taken from the official website), negotiated directly with the host; there is no booking through Ospitario. null: the operator gave no price.","type":"object","properties":{"nightlyFrom":{"description":"Lowest nightly price among the current and future periods","type":"number"},"currency":{"type":"string","enum":["EUR"]},"label":{"description":"e.g. \"da 120 €/notte\"","type":"string"},"seasons":{"description":"Current and future periods; ended ones are left out","type":"array","items":{"type":"object","properties":{"nightlyFrom":{"description":"Lowest nightly price the operator states for this period","type":"number"},"currency":{"type":"string","enum":["EUR"]},"seasonLabel":{"description":"Season name in the operator's words","anyOf":[{"type":"string"},{"type":"null"}]},"validFrom":{"description":"First day of the period, YYYY-MM-DD; null: no start given","anyOf":[{"type":"string"},{"type":"null"}]},"validTo":{"description":"Last day of the period, YYYY-MM-DD; null: no end given","anyOf":[{"type":"string"},{"type":"null"}]},"label":{"type":"string"}},"required":["nightlyFrom","currency","seasonLabel","validFrom","validTo","label"],"additionalProperties":false}},"updatedAt":{"description":"When the operator last changed the prices, YYYY-MM-DD","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["nightlyFrom","currency","label","seasons","updatedAt"],"additionalProperties":false},{"type":"null"}]},"unclaimed":{"description":"true: an unclaimed passport (tier L0) built from the operator's official website; email and phone are not shown, write with send_inquiry","type":"boolean"},"summary":{"description":"Two neutral sentences composed automatically from the facts of an unclaimed passport; not the operator's words","anyOf":[{"type":"object","properties":{"text":{"type":"string"},"generated":{"type":"boolean","const":true}},"required":["text","generated"],"additionalProperties":false},{"type":"null"}]},"languages":{"description":"Languages the operator speaks, as written on their website (unclaimed passports)","type":"array","items":{"type":"string"}},"safety":{"description":"Safety equipment the operator states is present. Insurance status and safety equipment are host-declared, not verified: Ospitario has seen no policy and no device. An item not listed is absent or not stated: see safetyStated.","type":"array","items":{"type":"string","enum":["smokeDetector","gasDetector","coDetector","fireExtinguisher"]}},"safetyStated":{"description":"Each safety item: true present, false stated absent, null not stated. Insurance status and safety equipment are host-declared, not verified: Ospitario has seen no policy and no device.","type":"object","properties":{"smokeDetector":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"gasDetector":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"coDetector":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"fireExtinguisher":{"anyOf":[{"type":"boolean"},{"type":"null"}]}},"required":["smokeDetector","gasDetector","coDetector","fireExtinguisher"],"additionalProperties":false},"trust":{"description":"What Ospitario verified, by area: the managing account, authority over the property, platform listings","type":"object","properties":{"managedByHost":{"description":"A host account with a confirmed email manages this passport; false for an unclaimed (L0) passport. A confirmed email proves nothing about the property","type":"boolean"},"propertyAuthority":{"description":"Proofs that this operator may represent the property; empty when none. Independent of platform listings","type":"array","items":{"type":"object","properties":{"method":{"description":"operator_eid: eID identity matched to the registration holder (L3, Italy); document_review: documents checked by Ospitario's admin (LA)","type":"string","enum":["operator_eid","document_review"]},"date":{"description":"YYYY-MM-DD","type":"string"}},"required":["method","date"],"additionalProperties":false}},"verifiedListings":{"description":"Platform listings with their own listing-control proof (see references); 0 is normal for a property without platforms","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["managedByHost","propertyAuthority","verifiedListings"],"additionalProperties":false},"provenance":{"description":"Where the passport's facts come from; a proof level is about the operator and the listings, not about the house's features","type":"object","properties":{"facts":{"description":"Who states the description, capacity, rooms, amenities, pool, rules and price: the operator through their account, or (unclaimed) the operator's official website as read by Ospitario","type":"string","enum":["operator","official_website"]},"verified":{"description":"These facts are not checked by Ospitario. What is checked is named elsewhere: verification, references and trust (who may rent, which listings), registration.status (the number against the register)","type":"boolean","const":false},"factsUpdatedAt":{"description":"Last change of these facts, ISO timestamp; null: unknown. Calendar sync and verification have their own dates (availability.lastSync, verification.date)","anyOf":[{"type":"string"},{"type":"null"}]},"register":{"description":"Unclaimed only: the regional register completed facts the website does not state (CIN, municipality, category, beds, rooms); null: none from a register","anyOf":[{"type":"object","properties":{"source":{"description":"The register and its publisher, as the licence asks to name them","type":"string"},"license":{"type":"string","const":"CC BY 4.0"},"page":{"description":"The dataset's page","type":"string"},"recordDate":{"description":"Last change of the register record, YYYY-MM-DD","type":"string"}},"required":["source","license","page","recordDate"],"additionalProperties":false},{"type":"null"}]}},"required":["facts","verified","factsUpdatedAt","register"],"additionalProperties":false},"booking":{"description":"What a traveler can do with this passport: contact the operator, never book through Ospitario. Availability is separate (availability, blocked)","type":"object","properties":{"bookable":{"description":"Always false: Ospitario takes no bookings and no payment. A result, a free night or a sent inquiry reserves nothing; the operator confirms dates and price","type":"boolean","const":false},"contact":{"description":"direct: the operator's own channels are in contact, and send_inquiry mails the operator; relay_only: unclaimed, write with send_inquiry (the official website in contact.site is the operator's own page, not an inquiry channel of Ospitario). send_inquiry may still refuse, with a reason","type":"string","enum":["direct","relay_only"]}},"required":["bookable","contact"],"additionalProperties":false}},"required":["slug","name","municipality","province","country","type","capacity","bedrooms","amenities","pool","placeKind","bathrooms","petsAllowed","checkinFrom","checkoutUntil","location","minNights","beds","extraCosts","childrenAllowed","stepFreeAccess","unitCount","propertyKind","smokingAllowed","eventsAllowed","cleaningFee","securityDeposit","facilities","description","locationNotes","houseRules","cancellation","contact","verification","registration","references","availability","blocked","liabilityInsurance","priceFrom","unclaimed","summary","languages","safety","safetyStated","trust","provenance","booking"],"additionalProperties":false},"contactPageUrl":{"description":"Page with the passport and the operator's direct contact; give this link to the traveler","type":"string"}},"required":["found"],"additionalProperties":false}}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"issues":{"type":"array"}}}}}},"429":{"description":"More than 60 requests per minute from this client; see Retry-After"}}}},"/api/v1/lookup/name":{"get":{"operationId":"lookup_by_name","summary":"Look up a property by name","description":"Find passports by property name: exact or prefix match, at least 3 characters, at most 10 results, exact match first, then alphabetical. Optionally limited to a municipality. Every result is a property with a proven listing (L2/L2c), a verified operator (L3), a right to manage verified by document review (LA) or, marked L0 and unclaimed, facts from the operator's official website with nothing proven; the result names the tier and the date it was reached, and whether the registration number (Italy: CIN) was checked against the public register. Contact is direct with the operator and commission-free, so the traveler pays no platform fee. No result means nothing proven matches; nothing is inferred, estimated or filled in.","parameters":[{"name":"name","in":"query","required":true,"description":"Property name or its beginning, at least 3 characters","schema":{"description":"Property name or its beginning, at least 3 characters","type":"string","minLength":3,"maxLength":80}},{"name":"municipality","in":"query","required":false,"description":"Exact municipality name","schema":{"description":"Exact municipality name","type":"string","minLength":2,"maxLength":80}},{"name":"lang","in":"query","required":false,"description":"Language of labels in the result; defaults to en","schema":{"description":"Language of labels in the result; defaults to en","type":"string","enum":["it","de","en","es","pt","fr"]}}],"responses":{"200":{"description":"Result; an empty list or found:false is an honest not-found","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"municipality":{"type":"string"},"type":{"description":"Accommodation type as stated by the operator","type":"string"},"verification":{"type":"object","properties":{"tier":{"description":"Verification tier (docs: ADR 0012, 0017, 0024, 0025). L0 unclaimed: facts read from the operator's official website, nothing proven, the operator has not claimed the page; contact only through send_inquiry. L2 listing verified: the operator proved control of the platform listing (calendar export link with the listing id, platform email with a valid DKIM signature, or channel manager); since 2026-11-07 also their right to manage the property (LA or L3), and earlier L2 stands as it was reached. L2c listing calendar proven (Booking, Vrbo): the operator blocked a random date Ospitario named in that platform's calendar export within 48 hours; no new L2c since 2026-11-07. LA right to manage verified (document review): Ospitario's admin checked documents tying the operator to this property (registration record, deed, lease, mandate or company register); a person found them consistent, without eID, so it does not prove who holds the account and never proves a platform listing. L3 operator verified: the operator's eID identity (SPID/CIE) matches the CIN holder in the national register's PDF. L4 document verified (automated check): an ownership, lease or mandate document is consistent with that identity and the property; it states consistency, not authenticity. L5 manually verified: a reviewer checked the document (an optional upgrade; it does not affect search order).","type":"string","enum":["L0","L2","L2c","LA","L3","L4","L5"]},"label":{"description":"Human-readable name of the tier","type":"string"},"date":{"description":"Date the tier was reached, YYYY-MM-DD","type":"string"}},"required":["tier","label","date"],"additionalProperties":false},"contactPageUrl":{"description":"Page with the passport and the operator's direct contact; give this link to the traveler","type":"string"}},"required":["slug","name","municipality","type","verification","contactPageUrl"],"additionalProperties":false}}},"required":["results"],"additionalProperties":false}}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"issues":{"type":"array"}}}}}},"429":{"description":"More than 60 requests per minute from this client; see Retry-After"}}}},"/api/v1/places":{"get":{"operationId":"list_places","summary":"Where Ospitario has homes","description":"Where Ospitario has public passports: every municipality with at least one, its region (Italy) and country, how many passports (and how many of them unclaimed, tier L0), and its list page. Call it when the traveler names an area, before searching: a place not listed has no passport on Ospitario yet; say so instead of searching it. Coverage is still small and grows week by week. Every result is a property with a proven listing (L2/L2c), a verified operator (L3), a right to manage verified by document review (LA) or, marked L0 and unclaimed, facts from the operator's official website with nothing proven; the result names the tier and the date it was reached, and whether the registration number (Italy: CIN) was checked against the public register. Contact is direct with the operator and commission-free, so the traveler pays no platform fee. No result means nothing proven matches; nothing is inferred, estimated or filled in.","parameters":[{"name":"country","in":"query","required":false,"description":"ISO 3166-1 alpha-2 country code to list: IT, DE, ES, FR or PT; all when omitted","schema":{"description":"ISO 3166-1 alpha-2 country code to list: IT, DE, ES, FR or PT; all when omitted","type":"string","enum":["IT","DE","ES","FR","PT"]}},{"name":"lang","in":"query","required":false,"description":"Language of labels in the result; defaults to en","schema":{"description":"Language of labels in the result; defaults to en","type":"string","enum":["it","de","en","es","pt","fr"]}}],"responses":{"200":{"description":"Result; an empty list or found:false is an honest not-found","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"description":"Public passports in the places listed","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"places":{"description":"Every municipality with at least one public passport, by country, region and name","type":"array","items":{"type":"object","properties":{"country":{"description":"ISO 3166-1 alpha-2 country code","type":"string"},"region":{"description":"Italian region (official name, e.g. Puglia); null outside Italy or when the passport names no province","anyOf":[{"type":"string"},{"type":"null"}]},"municipality":{"type":"string"},"province":{"description":"Region code as on the passports (IT province, e.g. LE); null when not stated","anyOf":[{"type":"string"},{"type":"null"}]},"passports":{"description":"Public passports in this municipality, unclaimed ones included","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"unclaimed":{"description":"Of these, unclaimed passports (tier L0): facts from the operator's website, nothing proven","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"pageUrl":{"description":"The municipality's list page on ospitario.com (Italy); null where none exists","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["country","region","municipality","province","passports","unclaimed","pageUrl"],"additionalProperties":false}}},"required":["total","places"],"additionalProperties":false}}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"issues":{"type":"array"}}}}}},"429":{"description":"More than 60 requests per minute from this client; see Retry-After"}}}},"/api/v1/passport/{slug}":{"get":{"operationId":"get_passport","summary":"Get a property passport","description":"Full passport of one property: attributes stated by the operator (provenance says who states them and when they changed; they are not checked by Ospitario), the pool's stated facets (null: not stated), tier and date, registration status, direct contact, blocked dates, liability insurance and safety equipment as declared by the operator, priceFrom (indicative, negotiated directly, no booking), and the page link to hand to the traveler. No booking through Ospitario; an inquiry can be sent to the operator with send_inquiry, or the traveler uses the direct contact on the passport. Insurance status and safety equipment are host-declared, not verified: Ospitario has seen no policy and no device. Availability is a hint, never a booking commitment: a night not blocked in the operator's synced calendar may already be taken, since the calendar is a copy that can lag behind; only the operator confirms availability, and Ospitario holds or books nothing. Prices are indicative, stated by the host (on an unclaimed passport: taken from the official website), negotiated directly with the host; there is no booking through Ospitario. Every result is a property with a proven listing (L2/L2c), a verified operator (L3), a right to manage verified by document review (LA) or, marked L0 and unclaimed, facts from the operator's official website with nothing proven; the result names the tier and the date it was reached, and whether the registration number (Italy: CIN) was checked against the public register. Contact is direct with the operator and commission-free, so the traveler pays no platform fee. No result means nothing proven matches; nothing is inferred, estimated or filled in.","parameters":[{"name":"slug","in":"path","required":true,"schema":{"description":"Passport slug from a search or lookup result","type":"string","pattern":"^[a-z0-9][a-z0-9-]{0,79}$"}},{"name":"lang","in":"query","required":false,"description":"Language of labels in the result; defaults to en","schema":{"description":"Language of labels in the result; defaults to en","type":"string","enum":["it","de","en","es","pt","fr"]}}],"responses":{"200":{"description":"Result; an empty list or found:false is an honest not-found","content":{"application/json":{"schema":{"type":"object","properties":{"found":{"type":"boolean"},"reason":{"description":"not_found: no public passport has this slug","type":"string","enum":["not_found"]},"property":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"municipality":{"type":"string"},"province":{"description":"Region code, ISO 3166-2 without the country prefix: IT/ES province (LE, GR), FR département (75), DE Land (HH), PT distrito (11)","anyOf":[{"type":"string"},{"type":"null"}]},"country":{"description":"ISO 3166-1 alpha-2 country code","type":"string"},"type":{"description":"Accommodation type as stated by the operator","type":"string"},"capacity":{"description":"Maximum number of guests","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"bedrooms":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"amenities":{"description":"Amenities in the operator's own words","type":"array","items":{"type":"string"}},"pool":{"description":"The pool, facet by facet; null: not stated. Never inferred.","type":"object","properties":{"present":{"description":"true: the operator declares a pool, or a line names a pool of the house; false: declared or stated absent; null: not stated","anyOf":[{"type":"boolean"},{"type":"null"}]},"access":{"description":"null: not stated, or the lines disagree","anyOf":[{"type":"string","enum":["private","shared"]},{"type":"null"}]},"setting":{"description":"null: not stated","anyOf":[{"type":"string","enum":["indoor","outdoor"]},{"type":"null"}]},"heated":{"description":"true: a heated or heatable pool. It does not say the pool is heated on given dates: see heatedSeason and heating. null: not stated","anyOf":[{"type":"boolean"},{"type":"null"}]},"heating":{"description":"As the operator declares it: no heating, heating included, heating for a surcharge, heating on request (notice in notes); null: not declared","anyOf":[{"type":"string","enum":["none","included","surcharge","on_request"]},{"type":"null"}]},"season":{"description":"Days the pool is open every year, MM-DD to MM-DD inclusive (may run across New Year); null when several periods are declared (see seasons); null: not declared, ask the operator","anyOf":[{"type":"object","properties":{"from":{"description":"MM-DD","type":"string"},"until":{"description":"MM-DD, inclusive","type":"string"}},"required":["from","until"],"additionalProperties":false},{"type":"null"}]},"heatedSeason":{"description":"Days the pool is heated every year, MM-DD to MM-DD; null: not declared, or several periods (see heatedSeasons)","anyOf":[{"type":"object","properties":{"from":{"description":"MM-DD","type":"string"},"until":{"description":"MM-DD, inclusive","type":"string"}},"required":["from","until"],"additionalProperties":false},{"type":"null"}]},"seasons":{"description":"Every period the pool is open each year, as the operator declares them; empty: not declared, ask the operator","type":"array","items":{"type":"object","properties":{"from":{"description":"MM-DD","type":"string"},"until":{"description":"MM-DD, inclusive","type":"string"}},"required":["from","until"],"additionalProperties":false}},"heatedSeasons":{"description":"Every period the pool is heated each year; empty: not declared","type":"array","items":{"type":"object","properties":{"from":{"description":"MM-DD","type":"string"},"until":{"description":"MM-DD, inclusive","type":"string"}},"required":["from","until"],"additionalProperties":false}},"notes":{"description":"Conditions in the operator's words: surcharge, notice for heating, hours, age rules","anyOf":[{"type":"string"},{"type":"null"}]},"source":{"description":"operator: declared in the passport's pool fields; amenity_text: read from the amenity lines by fixed patterns in six languages, a line that places the pool elsewhere (public, nearby) does not count; null: nothing about a pool","anyOf":[{"type":"string","enum":["operator","amenity_text"]},{"type":"null"}]}},"required":["present","access","setting","heated","heating","season","heatedSeason","seasons","heatedSeasons","notes","source"],"additionalProperties":false},"placeKind":{"description":"What the guest rents: the entire place, a private room or a shared room. Declared by the operator; null: not stated.","anyOf":[{"type":"string","enum":["entire","private_room","shared_room"]},{"type":"null"}]},"bathrooms":{"description":"Bathrooms; a half bath counts 0.5. null: not stated.","anyOf":[{"type":"number"},{"type":"null"}]},"petsAllowed":{"description":"Whether pets are allowed, as the operator states it; null: not stated, ask the operator.","anyOf":[{"type":"boolean"},{"type":"null"}]},"checkinFrom":{"description":"Check-in from, HH:MM local time; null: not stated","anyOf":[{"type":"string"},{"type":"null"}]},"checkoutUntil":{"description":"Checkout until, HH:MM local time; null: not stated","anyOf":[{"type":"string"},{"type":"null"}]},"location":{"description":"Exact location and address, only when the operator chose to publish them; never for an unclaimed passport","anyOf":[{"type":"object","properties":{"latitude":{"type":"number"},"longitude":{"type":"number"},"streetAddress":{"anyOf":[{"type":"string"},{"type":"null"}]},"postalCode":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["latitude","longitude","streetAddress","postalCode"],"additionalProperties":false},{"type":"null"}]},"minNights":{"description":"Minimum stay in nights as the operator states it; null: not stated, ask the operator","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"beds":{"description":"Beds by kind as the operator states them; null: not stated","anyOf":[{"type":"object","properties":{"double":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"single":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"sofa":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"bunk":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["double","single","sofa","bunk"],"additionalProperties":false},{"type":"null"}]},"extraCosts":{"description":"Costs beyond the nightly price in the operator's words (cleaning, tourist tax, linen, energy); null: not stated, which is not the same as none","anyOf":[{"type":"string"},{"type":"null"}]},"childrenAllowed":{"description":"Whether children are welcome, as the operator states it; null: not stated","anyOf":[{"type":"boolean"},{"type":"null"}]},"stepFreeAccess":{"description":"Whether the home can be entered without steps, as the operator states it; null: not stated. Not an accessibility certification","anyOf":[{"type":"boolean"},{"type":"null"}]},"unitCount":{"description":"Separately rentable homes this passport describes; 1: one home; more: ask the operator which unit the facts are for; null: not stated","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"propertyKind":{"description":"Kind of building from a fixed list (farmhouse: masseria, casale; trullo: Apulian trullo); type keeps the operator's own word. null: not stated","anyOf":[{"type":"string","enum":["apartment","house","villa","farmhouse","trullo","cottage","chalet","other"]},{"type":"null"}]},"smokingAllowed":{"description":"Whether smoking is allowed inside, as the operator states it; null: not stated","anyOf":[{"type":"boolean"},{"type":"null"}]},"eventsAllowed":{"description":"Whether parties or events are allowed, as the operator states it; null: not stated","anyOf":[{"type":"boolean"},{"type":"null"}]},"cleaningFee":{"description":"Cleaning fee per stay as the operator states it; null: not stated (which is not the same as none; see extraCosts)","anyOf":[{"type":"object","properties":{"amount":{"description":"Per stay, as stated; 0: none","type":"number"},"currency":{"type":"string","const":"EUR"}},"required":["amount","currency"],"additionalProperties":false},{"type":"null"}]},"securityDeposit":{"description":"Security deposit per stay as the operator states it; null: not stated","anyOf":[{"type":"object","properties":{"amount":{"description":"Per stay, as stated; 0: none","type":"number"},"currency":{"type":"string","const":"EUR"}},"required":["amount","currency"],"additionalProperties":false},{"type":"null"}]},"facilities":{"description":"true: there, false: stated absent, null: not stated. The operator's yes/no wins; otherwise read from the amenity lines by fixed patterns, as for the pool","type":"object","properties":{"parking":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"workspace":{"description":"A place to work (desk); not a statement about the internet speed","anyOf":[{"type":"boolean"},{"type":"null"}]},"airConditioning":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"heating":{"anyOf":[{"type":"boolean"},{"type":"null"}]}},"required":["parking","workspace","airConditioning","heating"],"additionalProperties":false},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"locationNotes":{"anyOf":[{"type":"string"},{"type":"null"}]},"houseRules":{"anyOf":[{"type":"string"},{"type":"null"}]},"cancellation":{"anyOf":[{"type":"string"},{"type":"null"}]},"contact":{"description":"Direct contact of the operator; no commission and no intermediary","type":"object","properties":{"phone":{"anyOf":[{"type":"string"},{"type":"null"}]},"whatsapp":{"anyOf":[{"type":"string"},{"type":"null"}]},"email":{"anyOf":[{"type":"string"},{"type":"null"}]},"site":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["phone","whatsapp","email","site"],"additionalProperties":false},"verification":{"description":"Strongest current tier of the property and its listings","anyOf":[{"type":"object","properties":{"tier":{"description":"Verification tier (docs: ADR 0012, 0017, 0024, 0025). L0 unclaimed: facts read from the operator's official website, nothing proven, the operator has not claimed the page; contact only through send_inquiry. L2 listing verified: the operator proved control of the platform listing (calendar export link with the listing id, platform email with a valid DKIM signature, or channel manager); since 2026-11-07 also their right to manage the property (LA or L3), and earlier L2 stands as it was reached. L2c listing calendar proven (Booking, Vrbo): the operator blocked a random date Ospitario named in that platform's calendar export within 48 hours; no new L2c since 2026-11-07. LA right to manage verified (document review): Ospitario's admin checked documents tying the operator to this property (registration record, deed, lease, mandate or company register); a person found them consistent, without eID, so it does not prove who holds the account and never proves a platform listing. L3 operator verified: the operator's eID identity (SPID/CIE) matches the CIN holder in the national register's PDF. L4 document verified (automated check): an ownership, lease or mandate document is consistent with that identity and the property; it states consistency, not authenticity. L5 manually verified: a reviewer checked the document (an optional upgrade; it does not affect search order).","type":"string","enum":["L0","L2","L2c","LA","L3","L4","L5"]},"label":{"description":"Human-readable name of the tier","type":"string"},"date":{"description":"Date the tier was reached, YYYY-MM-DD","type":"string"}},"required":["tier","label","date"],"additionalProperties":false},{"type":"null"}]},"registration":{"description":"Registration number status; null if the operator gave none","anyOf":[{"type":"object","properties":{"number":{"description":"The registration number as the operator declared it (Italy: CIN); checked only as far as status says","type":"string"},"status":{"description":"unchecked: the operator declared the country's short-term rental registration number (Italy: CIN), not yet checked against the public register; exists: the number is in the register; missing: the register no longer lists it.","type":"string","enum":["unchecked","exists","missing"]},"label":{"type":"string"},"checkedAt":{"description":"Day the number was last found in the official source (YYYY-MM-DD); a match of the code, never a check of the operator's identity","anyOf":[{"type":"string"},{"type":"null"}]},"source":{"description":"The official source that confirmed the number, with its licence; null when none did","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["number","status","label","checkedAt","source"],"additionalProperties":false},{"type":"null"}]},"references":{"description":"Platform listings proven to belong to this operator, each with its own tier, date and passed proofs","type":"array","items":{"type":"object","properties":{"domain":{"type":"string"},"listingId":{"description":"The platform's own listing id (Booking: country/slug)","type":"string"},"tier":{"type":"string","enum":["L2","L2c"]},"label":{"type":"string"},"date":{"type":"string"},"proofs":{"description":"Passed proofs only, with method and date","type":"array","items":{"type":"object","properties":{"method":{"description":"How listing control was proven. airbnb_calendar: the operator's Airbnb calendar export link carries the listing id; date_challenge: Ospitario named a random date, and the operator blocked it in the platform's calendar export within 48 hours (not used for new proofs since 2026-11-07); platform_email: a platform email to the operator with a valid DKIM signature; channel_manager: the operator's channel manager lists the listing.","type":"string","enum":["airbnb_calendar","date_challenge","platform_email","channel_manager"]},"label":{"type":"string"},"date":{"description":"Last passed check, YYYY-MM-DD","type":"string"}},"required":["method","label","date"],"additionalProperties":false}}},"required":["domain","listingId","tier","label","date","proofs"],"additionalProperties":false}},"availability":{"type":"object","properties":{"status":{"description":"calendar: blocked dates come from the operator's calendar, synced recently (lastSync); unblocked nights are not confirmed free; on_request: the operator answers availability on request, no dates are published; unknown: no current calendar, ask the operator. Availability is a hint, never a booking commitment: a night not blocked in the operator's synced calendar may already be taken, since the calendar is a copy that can lag behind; only the operator confirms availability, and Ospitario holds or books nothing.","type":"string","enum":["calendar","on_request","unknown"]},"lastSync":{"description":"Last successful calendar sync, ISO timestamp","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["status","lastSync"],"additionalProperties":false},"blocked":{"description":"Blocked date ranges from the operator's calendar as last synced; a night not listed is not confirmed free","type":"array","items":{"type":"object","properties":{"from":{"description":"First blocked night, YYYY-MM-DD","type":"string"},"to":{"description":"Checkout day, YYYY-MM-DD (exclusive)","type":"string"}},"required":["from","to"],"additionalProperties":false}},"liabilityInsurance":{"anyOf":[{"description":"Liability insurance (RC). Insurance status and safety equipment are host-declared, not verified: Ospitario has seen no policy and no device. null: the operator said nothing. The traveler should ask the operator for the policy before booking; platform guarantees (e.g. AirCover) do not cover direct bookings.","type":"object","properties":{"status":{"description":"declared: the operator states a liability insurance (RC) policy; none: the operator states there is none","type":"string","enum":["declared","none"]},"insurer":{"description":"Insurer as named by the operator","anyOf":[{"type":"string"},{"type":"null"}]},"validUntil":{"description":"End of the policy as stated by the operator, YYYY-MM-DD","anyOf":[{"type":"string"},{"type":"null"}]},"label":{"type":"string"}},"required":["status","insurer","validUntil","label"],"additionalProperties":false},{"type":"null"}]},"priceFrom":{"anyOf":[{"description":"Indicative price per night. Prices are indicative, stated by the host (on an unclaimed passport: taken from the official website), negotiated directly with the host; there is no booking through Ospitario. null: the operator gave no price.","type":"object","properties":{"nightlyFrom":{"description":"Lowest nightly price among the current and future periods","type":"number"},"currency":{"type":"string","enum":["EUR"]},"label":{"description":"e.g. \"da 120 €/notte\"","type":"string"},"seasons":{"description":"Current and future periods; ended ones are left out","type":"array","items":{"type":"object","properties":{"nightlyFrom":{"description":"Lowest nightly price the operator states for this period","type":"number"},"currency":{"type":"string","enum":["EUR"]},"seasonLabel":{"description":"Season name in the operator's words","anyOf":[{"type":"string"},{"type":"null"}]},"validFrom":{"description":"First day of the period, YYYY-MM-DD; null: no start given","anyOf":[{"type":"string"},{"type":"null"}]},"validTo":{"description":"Last day of the period, YYYY-MM-DD; null: no end given","anyOf":[{"type":"string"},{"type":"null"}]},"label":{"type":"string"}},"required":["nightlyFrom","currency","seasonLabel","validFrom","validTo","label"],"additionalProperties":false}},"updatedAt":{"description":"When the operator last changed the prices, YYYY-MM-DD","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["nightlyFrom","currency","label","seasons","updatedAt"],"additionalProperties":false},{"type":"null"}]},"unclaimed":{"description":"true: an unclaimed passport (tier L0) built from the operator's official website; email and phone are not shown, write with send_inquiry","type":"boolean"},"summary":{"description":"Two neutral sentences composed automatically from the facts of an unclaimed passport; not the operator's words","anyOf":[{"type":"object","properties":{"text":{"type":"string"},"generated":{"type":"boolean","const":true}},"required":["text","generated"],"additionalProperties":false},{"type":"null"}]},"languages":{"description":"Languages the operator speaks, as written on their website (unclaimed passports)","type":"array","items":{"type":"string"}},"safety":{"description":"Safety equipment the operator states is present. Insurance status and safety equipment are host-declared, not verified: Ospitario has seen no policy and no device. An item not listed is absent or not stated: see safetyStated.","type":"array","items":{"type":"string","enum":["smokeDetector","gasDetector","coDetector","fireExtinguisher"]}},"safetyStated":{"description":"Each safety item: true present, false stated absent, null not stated. Insurance status and safety equipment are host-declared, not verified: Ospitario has seen no policy and no device.","type":"object","properties":{"smokeDetector":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"gasDetector":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"coDetector":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"fireExtinguisher":{"anyOf":[{"type":"boolean"},{"type":"null"}]}},"required":["smokeDetector","gasDetector","coDetector","fireExtinguisher"],"additionalProperties":false},"trust":{"description":"What Ospitario verified, by area: the managing account, authority over the property, platform listings","type":"object","properties":{"managedByHost":{"description":"A host account with a confirmed email manages this passport; false for an unclaimed (L0) passport. A confirmed email proves nothing about the property","type":"boolean"},"propertyAuthority":{"description":"Proofs that this operator may represent the property; empty when none. Independent of platform listings","type":"array","items":{"type":"object","properties":{"method":{"description":"operator_eid: eID identity matched to the registration holder (L3, Italy); document_review: documents checked by Ospitario's admin (LA)","type":"string","enum":["operator_eid","document_review"]},"date":{"description":"YYYY-MM-DD","type":"string"}},"required":["method","date"],"additionalProperties":false}},"verifiedListings":{"description":"Platform listings with their own listing-control proof (see references); 0 is normal for a property without platforms","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["managedByHost","propertyAuthority","verifiedListings"],"additionalProperties":false},"provenance":{"description":"Where the passport's facts come from; a proof level is about the operator and the listings, not about the house's features","type":"object","properties":{"facts":{"description":"Who states the description, capacity, rooms, amenities, pool, rules and price: the operator through their account, or (unclaimed) the operator's official website as read by Ospitario","type":"string","enum":["operator","official_website"]},"verified":{"description":"These facts are not checked by Ospitario. What is checked is named elsewhere: verification, references and trust (who may rent, which listings), registration.status (the number against the register)","type":"boolean","const":false},"factsUpdatedAt":{"description":"Last change of these facts, ISO timestamp; null: unknown. Calendar sync and verification have their own dates (availability.lastSync, verification.date)","anyOf":[{"type":"string"},{"type":"null"}]},"register":{"description":"Unclaimed only: the regional register completed facts the website does not state (CIN, municipality, category, beds, rooms); null: none from a register","anyOf":[{"type":"object","properties":{"source":{"description":"The register and its publisher, as the licence asks to name them","type":"string"},"license":{"type":"string","const":"CC BY 4.0"},"page":{"description":"The dataset's page","type":"string"},"recordDate":{"description":"Last change of the register record, YYYY-MM-DD","type":"string"}},"required":["source","license","page","recordDate"],"additionalProperties":false},{"type":"null"}]}},"required":["facts","verified","factsUpdatedAt","register"],"additionalProperties":false},"booking":{"description":"What a traveler can do with this passport: contact the operator, never book through Ospitario. Availability is separate (availability, blocked)","type":"object","properties":{"bookable":{"description":"Always false: Ospitario takes no bookings and no payment. A result, a free night or a sent inquiry reserves nothing; the operator confirms dates and price","type":"boolean","const":false},"contact":{"description":"direct: the operator's own channels are in contact, and send_inquiry mails the operator; relay_only: unclaimed, write with send_inquiry (the official website in contact.site is the operator's own page, not an inquiry channel of Ospitario). send_inquiry may still refuse, with a reason","type":"string","enum":["direct","relay_only"]}},"required":["bookable","contact"],"additionalProperties":false}},"required":["slug","name","municipality","province","country","type","capacity","bedrooms","amenities","pool","placeKind","bathrooms","petsAllowed","checkinFrom","checkoutUntil","location","minNights","beds","extraCosts","childrenAllowed","stepFreeAccess","unitCount","propertyKind","smokingAllowed","eventsAllowed","cleaningFee","securityDeposit","facilities","description","locationNotes","houseRules","cancellation","contact","verification","registration","references","availability","blocked","liabilityInsurance","priceFrom","unclaimed","summary","languages","safety","safetyStated","trust","provenance","booking"],"additionalProperties":false},"jsonLd":{"description":"schema.org VacationRental of the passport","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"contactPageUrl":{"description":"Page with the passport and the operator's direct contact; give this link to the traveler","type":"string"}},"required":["found"],"additionalProperties":false}}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"issues":{"type":"array"}}}}}},"429":{"description":"More than 60 requests per minute from this client; see Retry-After"}}}},"/api/v1/inquiry":{"post":{"operationId":"send_inquiry","summary":"Send an inquiry to the operator","description":"Send one inquiry from a traveler to the operator of a passport, by email through Ospitario (no booking, no payment, no commission). Two steps, and only with the traveler's consent: first call without code; Ospitario mails a six-digit code and a confirmation link to guest_email. Ask the traveler for the code, then call again with challengeId and code; if the traveler confirmed with the link instead, the inquiry is already sent and that call answers refused with reason used. The operator replies to the traveler's address directly. For an unclaimed passport (L0) this is the only way to write. Limits: 3 per traveler email and day, 10 per operator and day, identical messages once. When sent, the answer carries a reference that the operator's mail names too; give it to the traveler.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"slug":{"description":"Passport slug from a search or lookup result","type":"string","pattern":"^[a-z0-9][a-z0-9-]{0,79}$"},"from":{"description":"Check-in date YYYY-MM-DD; requires to","type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"to":{"description":"Checkout date YYYY-MM-DD; requires from","type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"guests":{"description":"Number of guests","type":"integer","minimum":1,"maximum":50},"message":{"description":"The traveler's message to the operator, in the traveler's words","type":"string","minLength":10,"maxLength":2000},"guest_email":{"description":"The traveler's email address; the operator replies there","type":"string","maxLength":200,"format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"challengeId":{"description":"From step 1; send it with code in step 2","type":"string","minLength":10,"maxLength":40},"code":{"description":"The six-digit code the traveler received by email, for step 2","type":"string","pattern":"^\\d{6}$"},"lang":{"description":"Language of labels in the result; defaults to en","type":"string","enum":["it","de","en","es","pt","fr"]}},"required":["slug","guests","message","guest_email"],"additionalProperties":false}}}},"responses":{"200":{"description":"code_sent, sent or refused with a reason","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"code_sent: the code was handed to the mail server for guest_email; ask the traveler for it, then call again with challengeId and code (the traveler may confirm with the mail's link instead). sent: the inquiry was handed to the mail server for the operator, Reply-To the traveler; it is not a sign the operator read or answered it, and answers go to guest_email, not to Ospitario. Calling step 2 again with the same challengeId and code returns the same reference. refused: see reason","type":"string","enum":["code_sent","sent","refused"]},"challengeId":{"type":"string"},"reference":{"description":"With sent, or refused for delivery_failed: the inquiry's reference, also named in the operator's mail; quote it to the traveler and in any follow-up. Opaque, carries no personal data.","type":"string"},"reason":{"description":"Why nothing was sent: limits (3 per traveler and day, 10 per operator and day), the operator opted out, a repeated identical message, a wrong or expired code, used: already sent through the mail's confirmation link, delivery_failed: the mail server refused the mail (step 1: no code went out; step 2: the inquiry is recorded under reference but did not go out, the traveler may send it again), rate_limited: too many calls, try again in a minute","type":"string","enum":["not_found","opted_out","guest_daily","recipient_daily","global_daily","duplicate","codes_daily","no_recipient","expired","used","too_many","wrong","invalid","delivery_failed","rate_limited"]}},"required":["status"],"additionalProperties":false}}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"issues":{"type":"array"}}}}}},"429":{"description":"More than 60 requests per minute from this client; see Retry-After"}}}},"/p/{slug}.json":{"get":{"operationId":"get_passport_jsonld","summary":"Passport as schema.org JSON-LD","description":"The JSON-LD embedded in the passport page: VacationRental plus osp: fields for proof level, verified platforms, availability and blocked dates.","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"JSON-LD","content":{"application/ld+json":{"schema":{"type":"object"}}}},"404":{"description":"No published passport with this slug"}}}}}}