Add travel discovery before inventory search.

The Discovery API converts travel intent into ranked destination and date opportunities before downstream supplier APIs are called. Use it as a pre-shopping decision layer to reduce unnecessary search fan-out. It is a planning endpoint, not an inventory endpoint.

Discovery v1

POST /api/v1/business/discovery

Production base URL

https://api.myescapeplan.app

Contract: travel.discovery.v1

Business scope: travel.discovery

Quick start

Three integration rules matter first.

Authenticate with X-API-KEY

Pilot API keys are provisioned with the travel.discovery scope. Test and live keys are isolated business tenants.

Use an idempotency key

Business Discovery requires an Idempotency-Key request header. Reuse it only when retrying the same logical request.

Treat Discovery as unverified

Discovery makes no live supplier calls. Every opportunity returns verification_status: not_verified by design.

Request example

Open-destination discovery

Open-destination discovery can be expressed using structured fields alone. Query text is optional; structured fields can constrain origin, party, budget, dates, categories and preferences. Exact destination_ids can also be supplied for constrained discovery.

curl --request POST \ 'https://api.myescapeplan.app/api/v1/business/discovery' \ --header 'Content-Type: application/json' \ --header 'X-API-KEY: YOUR_API_KEY' \ --header 'Idempotency-Key: discovery-example-001' \ --data '{ "query": "4 days next month, under £300pp, somewhere warm with direct flights", "origin": { "query": "London", "airport_iata_codes": ["LHR", "LGW", "STN", "LTN", "LCY"] }, "party": { "adults": 2, "children": 0 }, "budget": { "amount": 300, "currency": "GBP", "scope": "per_person" }, "limit": 10 }'

Response example

Stable public opportunities, not planner internals.

Raw planner scores and internal lanes are deliberately private. Downstream products receive ordered opportunities, reasons and qualitative fit: strong, possible, stretch or unknown.

{ "request_id": "req_…", "idempotency_key": "discovery-example-001", "status": "ok", "discovery_id": "…", "interpreted_request": { "title": "4 days next month, under £300pp, somewhere warm with direct flights", "origin": "London", "duration_nights": 4, "adults": 2, "children": 0, "budget_amount": 300, "budget_currency": "GBP", "budget_scope": "per_person", "categories": ["flights", "accommodation"], "warnings": [] }, "opportunities": [ { "opportunity_id": "…", "destination": { "id": "00000000-0000-0000-0000-000000000000", "name": "Málaga", "display_name": "Málaga, Spain", "country_code": "ES" }, "rank": 1, "date_options": [ { "start_date": "2026-09-10", "end_date": "2026-09-14", "nights": 4 } ], "tags": ["warm"], "reasons": ["Matches the requested warm short-break intent."], "fit": { "label": "strong", "reason": "Strong match to the interpreted request." }, "origin_airport_iata_codes": ["LHR", "LGW", "STN", "LTN", "LCY"], "destination_airport_iata_codes": ["AGP"], "search_inputs_available": { "flights": true, "accommodation": true, "events": true }, "verification_status": "not_verified" } ], "meta": { "contract_version": "travel.discovery.v1", "candidate_count": 1, "usage": { "metering_basis": "request", "discoveries_used": 1, "candidate_count": 1, "plan_period_allowance": 50000 } }, "expires_at": "2026-08-13T12:00:00Z" }

Capability boundary

Discovery decides what is worth shopping. Verified Search shops it.

Provider-backed verification is intentionally separate from the synchronous Discovery API. Pilots that need live flight, accommodation or event checks can use the asynchronous Verified Search workflow with a separately scoped key.

Discovery

POST /api/v1/business/discovery

Scope: travel.discovery

No supplier calls · synchronous planning

Verified Search

POST /api/v1/business/searches

Scope: travel.search

Provider-backed · asynchronous · pilot configuration

Integration notes

Current v1 boundaries

Open-destination discovery supports structured fields without query text; explicit destination_ids can be supplied for constrained discovery.

limit accepts 1–50, while the deployed service may enforce a lower configured candidate cap.

Business usage is metered per admitted Discovery request, including no-results responses.

fit is qualitative planning suitability, not statistical confidence.

verification_status remains not_verified on the Discovery endpoint.

API keys, quotas and provider-backed Verified Search are provisioned as part of a pilot agreement.

MyEscapePlan Travel Intelligence

Travel discovery infrastructure for reducing search fan-out, plus travel shopping data and market intelligence.

MYESCAPEPLAN LTD · Company no. 16395758 · Registered in United Kingdom

Discovery API is available now. Destination & Market Shopping Intelligence is coming soon.

Shopping Intelligence case studies will publish when the benchmark and methodology are ready for public release.

Legal

Terms & conditions

Privacy