{
  "openapi": "3.0.1",
  "info": {
    "title": "Hotel Price Comparison & Deal Finder",
    "description": "Compare hotel prices from Booking.com, Expedia, Agoda, Trip.com & more in one run. Normalizes rooms, currencies and taxes, then ranks offers with a 0–100 Deal Score to reveal where a hotel is truly cheapest. Free — just paste the hotel's TripAdvisor link.",
    "version": "1.0",
    "x-build-id": "echTsw3uUugrrb2zx"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/alpercsv~hotel-deal-arbitrage-finder/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-alpercsv-hotel-deal-arbitrage-finder",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/acts/alpercsv~hotel-deal-arbitrage-finder/runs": {
      "post": {
        "operationId": "runs-sync-alpercsv-hotel-deal-arbitrage-finder",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor and returns information about the initiated run in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/runsResponseSchema"
                }
              }
            }
          }
        }
      }
    },
    "/acts/alpercsv~hotel-deal-arbitrage-finder/run-sync": {
      "post": {
        "operationId": "run-sync-alpercsv-hotel-deal-arbitrage-finder",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "inputSchema": {
        "type": "object",
        "required": [
          "checkIn",
          "checkOut"
        ],
        "properties": {
          "hotelName": {
            "title": "Hotel name",
            "type": "string",
            "description": "Name of the hotel to compare, e.g. \"Charisma De Luxe Hotel\". With just name + destination the Actor finds the hotel's TripAdvisor page automatically; adding \"tripAdvisorUrl\" makes identification 100% reliable. Leave empty only when using the bulk \"hotels\" list."
          },
          "destination": {
            "title": "Destination",
            "type": "string",
            "description": "City and country of the hotel, e.g. \"Kusadasi, Turkey\". Used for automatic hotel identification and to disambiguate similar names. In bulk mode this is the fallback destination for entries without their own."
          },
          "checkIn": {
            "title": "Check-in date",
            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
            "type": "string",
            "description": "Check-in date in ISO format (YYYY-MM-DD). Must not be in the past."
          },
          "checkOut": {
            "title": "Check-out date",
            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
            "type": "string",
            "description": "Check-out date in ISO format (YYYY-MM-DD). Must be after check-in; stays up to 30 nights are supported."
          },
          "adults": {
            "title": "Adults",
            "minimum": 1,
            "maximum": 16,
            "type": "integer",
            "description": "Number of adult guests.",
            "default": 2
          },
          "children": {
            "title": "Children",
            "minimum": 0,
            "maximum": 8,
            "type": "integer",
            "description": "Number of children.",
            "default": 0
          },
          "childrenAges": {
            "title": "Children ages",
            "type": "array",
            "description": "Age of each child (0-17). When provided, the count must match the \"children\" field.",
            "default": []
          },
          "rooms": {
            "title": "Rooms",
            "minimum": 1,
            "maximum": 8,
            "type": "integer",
            "description": "Number of rooms.",
            "default": 1
          },
          "currency": {
            "title": "Currency",
            "type": "string",
            "description": "3-letter ISO currency code all prices are normalized into (live ECB rates; offers are dropped rather than converted with invented rates).",
            "default": "EUR"
          },
          "market": {
            "title": "Market / country",
            "type": "string",
            "description": "Optional 2-letter market code (e.g. \"TR\", \"DE\") passed to providers that support market-specific pricing."
          },
          "language": {
            "title": "Language",
            "type": "string",
            "description": "Language code for provider results where supported.",
            "default": "en"
          },
          "tripAdvisorUrl": {
            "title": "TripAdvisor hotel URL (optional)",
            "type": "string",
            "description": "Optional but recommended: the hotel's page URL on tripadvisor.com. It identifies the property with 100% certainty. Without it the Actor auto-resolves the hotel from name + destination (search-engine lookup, best-effort; or the Xotelo Search API when a \"rapidApiKey\" is provided)."
          },
          "hotels": {
            "title": "Bulk hotels (arbitrage scanner)",
            "type": "array",
            "description": "Bulk mode: scan up to 20 hotels in one run and get a ranked arbitrage table. Each entry: {\"hotelName\": \"...\", \"destination\": \"... (optional, falls back to the top-level destination)\", \"tripAdvisorUrl\": \"... (optional)\", \"tripAdvisorHotelKey\": \"g...-d... (optional)\"}. When non-empty, the top-level hotelName is ignored.",
            "default": []
          },
          "alerts": {
            "title": "Price alerts",
            "type": "object",
            "description": "Turn the Actor into a price monitor (combine with Apify Schedules): {\"maxTotalPrice\": 750, \"minSavingsPercent\": 20, \"minDealScore\": 80, \"webhookUrl\": \"https://...\", \"telegramBotToken\": \"...\", \"telegramChatId\": \"...\"}. A notification is sent when any scanned hotel matches the conditions.",
            "default": {}
          },
          "rapidApiKey": {
            "title": "RapidAPI key (reliable auto-lookup)",
            "type": "string",
            "description": "Optional RapidAPI key for Xotelo's Search endpoint — makes hotel-name auto-resolution reliable (the keyless search-engine fallback can be rate-limited). Free tier at rapidapi.com (search \"Xotelo\"). Alternatively set the RAPIDAPI_KEY environment variable."
          },
          "hotelUrls": {
            "title": "Additional hotel URLs",
            "type": "array",
            "description": "Optional additional URLs identifying the same hotel on other sites (used by future providers).",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "tripAdvisorHotelKey": {
            "title": "TripAdvisor hotel key",
            "type": "string",
            "description": "Alternative to the TripAdvisor URL: the raw location key like \"g297972-d302274\". When set, it takes precedence over the URL."
          },
          "serpApiKey": {
            "title": "SerpApi API key",
            "type": "string",
            "description": "Optional SerpApi key enabling the Google Hotels provider. Stored as a secret. Alternatively set the SERPAPI_API_KEY environment variable."
          },
          "maximumPrice": {
            "title": "Maximum total price",
            "minimum": 1,
            "type": "integer",
            "description": "Hide offers above this total price (in the selected currency). Market statistics still include them."
          },
          "minimumSavingsPercent": {
            "title": "Minimum savings %",
            "minimum": 0,
            "maximum": 95,
            "type": "integer",
            "description": "Hide offers saving less than this percentage vs the median equivalent offer."
          },
          "filters": {
            "title": "Condition filters",
            "type": "object",
            "description": "Optional condition filters: {\"refundableOnly\": false, \"breakfastIncludedOnly\": false, \"allInclusiveOnly\": false, \"taxesIncludedOnly\": false, \"providers\": []}",
            "default": {}
          },
          "sortBy": {
            "title": "Sort mode",
            "enum": [
              "price",
              "dealScore",
              "bestValue",
              "savingsPercent"
            ],
            "type": "string",
            "description": "How to order the offers in the output.",
            "default": "dealScore"
          },
          "maxOffersPerProvider": {
            "title": "Max offers per provider",
            "minimum": 1,
            "maximum": 100,
            "type": "integer",
            "description": "Cost-control cap on offers collected from each provider.",
            "default": 25
          },
          "enabledProviders": {
            "title": "Enabled providers",
            "type": "array",
            "description": "Restrict the run to these provider ids (empty = all available). Known ids: \"xotelo\", \"google-hotels\", \"mock\".",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "includeRawData": {
            "title": "Include raw provider data",
            "type": "boolean",
            "description": "Attach each provider's raw payload to offers (larger output, useful for debugging).",
            "default": false
          },
          "timeoutSecs": {
            "title": "Search timeout (seconds)",
            "minimum": 20,
            "maximum": 600,
            "type": "integer",
            "description": "Overall budget for provider searches. Providers still running when it elapses are aborted and reported as warnings.",
            "default": 120
          },
          "cacheTtlMinutes": {
            "title": "Cache TTL (minutes)",
            "minimum": 0,
            "maximum": 240,
            "type": "integer",
            "description": "Reuse provider results for identical searches within this window (0 disables caching). Hotel inventory changes fast, so 15-30 minutes is recommended.",
            "default": 20
          },
          "dealScoreWeights": {
            "title": "Deal Score weights",
            "type": "object",
            "description": "Optional overrides: {\"priceAdvantageMax\": 60, \"offerQualityMax\": 20, \"confidenceMax\": 20}."
          }
        }
      },
      "runsResponseSchema": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "actId": {
                "type": "string"
              },
              "userId": {
                "type": "string"
              },
              "startedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "finishedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "status": {
                "type": "string",
                "example": "READY"
              },
              "meta": {
                "type": "object",
                "properties": {
                  "origin": {
                    "type": "string",
                    "example": "API"
                  },
                  "userAgent": {
                    "type": "string"
                  }
                }
              },
              "stats": {
                "type": "object",
                "properties": {
                  "inputBodyLen": {
                    "type": "integer",
                    "example": 2000
                  },
                  "rebootCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "restartCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "resurrectCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "computeUnits": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "options": {
                "type": "object",
                "properties": {
                  "build": {
                    "type": "string",
                    "example": "latest"
                  },
                  "timeoutSecs": {
                    "type": "integer",
                    "example": 300
                  },
                  "memoryMbytes": {
                    "type": "integer",
                    "example": 1024
                  },
                  "diskMbytes": {
                    "type": "integer",
                    "example": 2048
                  }
                }
              },
              "buildId": {
                "type": "string"
              },
              "defaultKeyValueStoreId": {
                "type": "string"
              },
              "defaultDatasetId": {
                "type": "string"
              },
              "defaultRequestQueueId": {
                "type": "string"
              },
              "buildNumber": {
                "type": "string",
                "example": "1.0.0"
              },
              "containerUrl": {
                "type": "string"
              },
              "usage": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "integer",
                    "example": 1
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "usageTotalUsd": {
                "type": "number",
                "example": 0.00005
              },
              "usageUsd": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "number",
                    "example": 0.00005
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}