> ## Documentation Index > Fetch the complete documentation index at: https://docs.sanfoundation.com/llms.txt > Use this file to discover all available pages before exploring further. # Search hotels > Find hotels and vacation rentals for a stay. Find properties for a destination and stay of 1–30 nights. Check-in must be today or later in UTC. Use a returned `id` for [hotel details and rates](https://docs.sanfoundation.com/api-reference/hotels-details.md) or [guest reviews](https://docs.sanfoundation.com/api-reference/hotels-reviews.md). Only offer these actions when an ID is present. Star class and guest rating are separate fields. ## Example stay Generate future dates with Python 3, then search: ```bash theme={null} CHECK_IN=$(python3 -c 'from datetime import datetime, timedelta, timezone; print((datetime.now(timezone.utc) + timedelta(days=30)).date())') CHECK_OUT=$(python3 -c 'from datetime import datetime, timedelta, timezone; print((datetime.now(timezone.utc) + timedelta(days=33)).date())') curl --get 'https://api.sanfoundation.com/v1/hotels/search' \ --header "Authorization: Bearer $SAN_API_KEY" \ --data-urlencode 'query=Tokyo' \ --data-urlencode "check_in=$CHECK_IN" \ --data-urlencode "check_out=$CHECK_OUT" \ --data-urlencode 'currency=USD' ``` ## OpenAPI ````yaml https://api.sanfoundation.com/openapi.json GET /v1/hotels/search openapi: 3.0.0 info: title: SAN API description: >- Web data and context for agents, served by a network of miners running real browsers on residential connections. One resource per thing an agent asks for: search the web, read the news, find places, hotels and flights, and quote a symbol. Present an API key as `Authorization: Bearer san_...`. Every response is snake_case JSON and every error is `{ error: { code, message, param } }`. version: 0.0.1 contact: {} servers: [] security: [] tags: - name: web description: Web search - name: news description: News search - name: places description: Places search - name: hotels description: Stays search - name: flights description: Flight search - name: finance description: Quotes and charts - name: shopping description: Products and sellers - name: account description: Plan and remaining budget paths: /v1/hotels/search: get: tags: - hotels summary: Find places to stay description: >- Hotels and rentals for a destination and a set of dates, with nightly and total rates, rating, star class and amenities. Prices are for the exact stay, so the dates are required. operationId: HotelsController_search parameters: - name: page required: false in: query description: 1 based, up to 5. schema: type: number example: 1 - name: country required: false in: query description: ISO 3166-1 alpha-2. Defaults to `us`. schema: type: string example: us - name: currency required: false in: query description: ISO 4217. Defaults to the currency of `country`. schema: type: string example: USD - name: stars required: false in: query description: Comma list of star classes, 1 to 5. schema: example: 4,5 type: string - name: check_out required: true in: query description: YYYY-MM-DD. 1 to 30 nights after `check_in`. schema: example: '2026-10-19' type: string - name: check_in required: true in: query description: YYYY-MM-DD. Not in the past. schema: type: string example: '2026-10-15' - name: query required: true in: query description: 'The destination: a city, a neighbourhood or a landmark.' schema: example: Tokyo type: string responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/HotelsSearchResponseDto' '400': description: A parameter is missing, invalid or not recognized. content: application/json: schema: $ref: '#/components/schemas/PublicErrorDto' '401': description: Invalid API key. content: application/json: schema: $ref: '#/components/schemas/PublicErrorDto' '429': description: Monthly quota exhausted. Hard stop, no overage. content: application/json: schema: $ref: '#/components/schemas/PublicErrorDto' '503': description: No miner and no fallback could serve the request. content: application/json: schema: $ref: '#/components/schemas/PublicErrorDto' security: - api_key: [] - x-api-key: [] components: schemas: HotelsSearchResponseDto: type: object properties: id: type: string format: uuid description: Id of this request. Quote it when reporting a problem. took_ms: type: number example: 1420 description: How long the request took, in milliseconds. request: type: object additionalProperties: true description: >- The parameters as accepted, after defaults and normalization. What the request actually ran with. example: query: coffee country: us page: 1 next_page: type: number nullable: true example: 2 description: >- The next page to ask for, or null when there is no further page. Never a page this endpoint would reject. results: type: array items: $ref: '#/components/schemas/HotelResultDto' total_results: type: number example: 15000 description: Total matches reported for the search. currency: type: string example: USD description: ISO 4217 code the prices are quoted in. required: - id - took_ms - request - next_page - results PublicErrorDto: type: object properties: error: $ref: '#/components/schemas/PublicErrorBodyDto' required: - error HotelResultDto: type: object properties: id: type: string example: san1.QkFEQ0FGRTAxMjM0NTY3ODk description: Opaque handle for this property. position: type: number example: 1 name: type: string example: Park Hotel Tokyo type: type: string enum: - hotel - vacation_rental example: hotel rate_per_night: $ref: '#/components/schemas/MoneyDto' total_rate: description: Total for the stay. allOf: - $ref: '#/components/schemas/MoneyDto' rating: type: number example: 4.3 reviews: type: number example: 2841 stars: type: number example: 4 description: Star class, 1 to 5. amenities: example: - Free Wi-Fi - Pool type: array items: type: string required: - position - name - type PublicErrorBodyDto: type: object properties: code: type: string enum: - unauthorized - missing_parameter - invalid_parameter - not_found - quota_exceeded - rate_limited - unavailable - expired - internal_error example: missing_parameter message: type: string example: Missing parameter `query`. param: type: string example: query description: The parameter at fault, when one parameter is at fault. required: - code - message MoneyDto: type: object properties: amount: type: number example: 180 description: The amount as a number. display: type: string example: $180 description: The same amount as displayed, with its currency. required: - amount - display securitySchemes: api_key: scheme: bearer bearerFormat: JWT type: http description: 'Public API key: `Authorization: Bearer san_...`.' x-api-key: type: apiKey in: header name: X-Api-Key description: The same public API key, as a header. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.