Advertise with us
Reach travelers on high-intent pages across our marketplace.
Complete reference for the DownFare REST API. All endpoints return JSON and require authentication.
http://downfare.com/api/v1
Include your API key in the X-API-Key header with every request.
X-API-Key: your-api-key-here
Rate limits are enforced per API key. The default limit is 60 requests per minute. Rate limit headers are included in every response:
X-RateLimit-Limit: 60 X-RateLimit-Remaining: 58 X-RateLimit-Reset: 1718462400
All errors follow a consistent JSON format with an error code and human-readable message.
{
"error": "validation_error",
"message": "The origin field is required.",
"errors": {
"origin": ["The origin field is required."]
}
}
| Status Code | Description |
|---|---|
| 400 | Bad Request -- Invalid parameters |
| 401 | Unauthorized -- Invalid or missing API key |
| 403 | Forbidden -- Insufficient scopes |
| 404 | Not Found -- Resource does not exist |
| 422 | Validation Error -- Check the errors object |
| 429 | Too Many Requests -- Rate limit exceeded |
| 500 | Server Error -- Something went wrong on our end |
All API requests must be authenticated using an API key. Include your key in the X-API-Key header with every request. API keys are issued upon approval of your developer application.
/api/v1/*
All endpoints require authentication via the X-API-Key header.
| Name | Type | Required | Description |
|---|---|---|---|
| X-API-Key | header | Yes | Your unique API key provided upon approval. |
{
"error": "Unauthenticated.",
"message": "A valid API key is required. Include it as the X-API-Key header."
}
Search for flight offers across hundreds of airlines worldwide. Retrieve detailed offer information including pricing, segments, fare rules, seat maps, and real-time flight status.
/api/v1/flights/search
Search for available flight offers based on origin, destination, dates, and passenger counts.
| Name | Type | Required | Description |
|---|---|---|---|
| origin | string | Yes | IATA airport code for departure (e.g., JFK, LHR). |
| destination | string | Yes | IATA airport code for arrival (e.g., LAX, CDG). |
| departure_date | string | Yes | Departure date in YYYY-MM-DD format. |
| return_date | string | No | Return date in YYYY-MM-DD format. Omit for one-way flights. |
| adults | integer | No | Number of adult passengers (1-9). Defaults to 1. |
| children | integer | No | Number of child passengers (0-9). Defaults to 0. |
| infants | integer | No | Number of infant passengers (0-9). Defaults to 0. |
| travel_class | string | No | Cabin class: ECONOMY, PREMIUM_ECONOMY, BUSINESS, or FIRST. Defaults to ECONOMY. |
{
"data": [
{
"id": "offer_abc123",
"price": {
"amount": "349.00",
"currency": "USD"
},
"segments": [
{
"departure": "JFK",
"arrival": "LAX",
"departureTime": "2025-06-15T08:00:00",
"arrivalTime": "2025-06-15T11:30:00",
"airline": "AA",
"flightNumber": "AA100",
"duration": "PT5H30M"
}
],
"travelClass": "ECONOMY",
"seatsAvailable": 4
}
],
"meta": {
"total": 24,
"currency": "USD"
}
}
/api/v1/flights/offers/{offerId}
Retrieve detailed information for a specific flight offer, including fare rules and baggage allowances.
| Name | Type | Required | Description |
|---|---|---|---|
| offerId | string | Yes | The unique identifier of the flight offer. |
{
"data": {
"id": "offer_abc123",
"price": {
"amount": "349.00",
"currency": "USD"
},
"segments": [
{
"departure": "JFK",
"arrival": "LAX",
"departureTime": "2025-06-15T08:00:00",
"arrivalTime": "2025-06-15T11:30:00",
"airline": "AA",
"flightNumber": "AA100"
}
],
"fareRules": {
"refundable": false,
"changeable": true,
"changeFee": "75.00"
},
"baggageAllowance": {
"carryOn": "1 piece",
"checked": "1 piece (23kg)"
}
}
}
/api/v1/flights/offers/{offerId}/price
Get a confirmed, up-to-date price for a flight offer. Prices may change between search and booking, so always confirm before checkout.
| Name | Type | Required | Description |
|---|---|---|---|
| offerId | string | Yes | The unique identifier of the flight offer to price. |
{
"data": {
"offerId": "offer_abc123",
"price": {
"amount": "355.00",
"currency": "USD"
},
"priceChanged": true,
"seatsRemaining": 3
}
}
/api/v1/flights/offers/{offerId}/seatmap
Retrieve the seat map for a specific flight offer, showing available and occupied seats by cabin section.
| Name | Type | Required | Description |
|---|---|---|---|
| offerId | string | Yes | The unique identifier of the flight offer. |
{
"data": {
"cabins": [
{
"class": "ECONOMY",
"rows": [
{
"number": 10,
"seats": [
{
"column": "A",
"available": true,
"price": "15.00"
},
{
"column": "B",
"available": true,
"price": "0.00"
},
{
"column": "C",
"available": false,
"price": null
}
]
}
]
}
]
}
}
/api/v1/flights/status
Get real-time status for a specific flight by carrier code, flight number, and departure date.
| Name | Type | Required | Description |
|---|---|---|---|
| carrier_code | string | Yes | Two-letter IATA carrier code (e.g., AA, BA, LH). |
| flight_number | string | Yes | Flight number (e.g., 100, 2045). |
| departure_date | string | Yes | Departure date in YYYY-MM-DD format. |
{
"data": {
"flightNumber": "AA100",
"status": "on_time",
"departure": {
"airport": "JFK",
"scheduled": "2025-06-15T08:00:00",
"estimated": "2025-06-15T08:05:00",
"terminal": "8",
"gate": "B22"
},
"arrival": {
"airport": "LAX",
"scheduled": "2025-06-15T11:30:00",
"estimated": "2025-06-15T11:25:00"
}
}
}
/api/v1/flights/inspiration
Get inspiration flight deals from a given origin. Returns popular destinations with lowest available fares.
| Name | Type | Required | Description |
|---|---|---|---|
| origin | string | No | IATA airport code for departure. Returns global deals if omitted. |
{
"data": [
{
"destination": "BCN",
"city": "Barcelona",
"country": "ES",
"price": {
"amount": "199.00",
"currency": "USD"
},
"departureDate": "2025-07-01"
},
{
"destination": "FCO",
"city": "Rome",
"country": "IT",
"price": {
"amount": "249.00",
"currency": "USD"
},
"departureDate": "2025-07-05"
}
]
}
Search and retrieve hotel listings with room availability, pricing, and detailed property information.
/api/v1/hotels/search
Search for available hotels in a given destination with check-in and check-out dates.
| Name | Type | Required | Description |
|---|---|---|---|
| destination | string | Yes | City name, IATA code, or geographic coordinates. |
| checkInDate | string | Yes | Check-in date in YYYY-MM-DD format. |
| checkOutDate | string | Yes | Check-out date in YYYY-MM-DD format. |
| adults | integer | Yes | Number of adult guests (1-6). |
| rooms | integer | No | Number of rooms required. Defaults to 1. |
{
"data": [
{
"id": "hotel_xyz789",
"name": "Grand Plaza Hotel",
"starRating": 4,
"location": {
"city": "Paris",
"country": "FR",
"latitude": 48.8566,
"longitude": 2.3522
},
"price": {
"amount": "189.00",
"currency": "USD",
"perNight": true
},
"amenities": [
"wifi",
"pool",
"spa",
"restaurant"
],
"thumbnail": "https:\/\/example.com\/images\/hotel_xyz789.jpg"
}
],
"meta": {
"total": 56,
"currency": "USD"
}
}
/api/v1/hotels/{hotelId}
Get detailed information for a specific hotel, including room types and available rates.
| Name | Type | Required | Description |
|---|---|---|---|
| hotelId | string | Yes | The unique identifier of the hotel. |
{
"data": {
"id": "hotel_xyz789",
"name": "Grand Plaza Hotel",
"description": "A luxurious 4-star hotel in the heart of Paris.",
"starRating": 4,
"rooms": [
{
"type": "Standard Double",
"price": {
"amount": "189.00",
"currency": "USD"
},
"maxOccupancy": 2
},
{
"type": "Deluxe Suite",
"price": {
"amount": "349.00",
"currency": "USD"
},
"maxOccupancy": 3
}
],
"amenities": [
"wifi",
"pool",
"spa",
"restaurant",
"gym",
"parking"
],
"images": [
"https:\/\/example.com\/images\/hotel1.jpg",
"https:\/\/example.com\/images\/hotel2.jpg"
]
}
}
Browse vacation rental properties including apartments, villas, and holiday homes with availability and pricing.
/api/v1/rentals/search
Search for available vacation rental properties in a destination.
| Name | Type | Required | Description |
|---|---|---|---|
| destination | string | Yes | City name or region to search within. |
| checkInDate | string | Yes | Check-in date in YYYY-MM-DD format. |
| checkOutDate | string | Yes | Check-out date in YYYY-MM-DD format. |
| guests | integer | Yes | Number of guests (1-16). |
{
"data": [
{
"id": "rental_def456",
"title": "Cozy Apartment Near Eiffel Tower",
"propertyType": "apartment",
"bedrooms": 2,
"maxGuests": 4,
"price": {
"amount": "120.00",
"currency": "USD",
"perNight": true
},
"rating": 4.7,
"thumbnail": "https:\/\/example.com\/images\/rental_def456.jpg"
}
],
"meta": {
"total": 38,
"currency": "USD"
}
}
/api/v1/rentals/{rentalId}
Retrieve full details for a specific vacation rental property.
| Name | Type | Required | Description |
|---|---|---|---|
| rentalId | string | Yes | The unique identifier of the rental property. |
{
"data": {
"id": "rental_def456",
"title": "Cozy Apartment Near Eiffel Tower",
"description": "A beautifully furnished 2-bedroom apartment just minutes from the Eiffel Tower.",
"propertyType": "apartment",
"bedrooms": 2,
"bathrooms": 1,
"maxGuests": 4,
"amenities": [
"wifi",
"kitchen",
"washer",
"air_conditioning"
],
"houseRules": {
"no_smoking": true,
"no_parties": true,
"checkIn": "15:00",
"checkOut": "11:00"
},
"images": [
"https:\/\/example.com\/images\/rental1.jpg",
"https:\/\/example.com\/images\/rental2.jpg"
]
}
}
Discover tours, experiences, and activities available at destinations worldwide. Book guided tours, day trips, and unique experiences.
/api/v1/tours/search
Search for tours and activities available at a specific destination.
| Name | Type | Required | Description |
|---|---|---|---|
| destination | string | Yes | City or destination name. |
| date | string | No | Preferred activity date in YYYY-MM-DD format. |
| participants | integer | No | Number of participants. Defaults to 1. |
{
"data": [
{
"id": "tour_ghi012",
"title": "Skip-the-Line Eiffel Tower Tour",
"category": "sightseeing",
"duration": "PT3H",
"price": {
"amount": "65.00",
"currency": "USD",
"perPerson": true
},
"rating": 4.8,
"reviewCount": 1240,
"thumbnail": "https:\/\/example.com\/images\/tour_ghi012.jpg"
}
],
"meta": {
"total": 89,
"currency": "USD"
}
}
/api/v1/tours/{activityId}
Get detailed information about a specific tour or activity, including availability and booking options.
| Name | Type | Required | Description |
|---|---|---|---|
| activityId | string | Yes | The unique identifier of the tour or activity. |
{
"data": {
"id": "tour_ghi012",
"title": "Skip-the-Line Eiffel Tower Tour",
"description": "Enjoy priority access to the Eiffel Tower with an expert local guide.",
"category": "sightseeing",
"duration": "PT3H",
"languages": [
"en",
"fr",
"es"
],
"includes": [
"Skip-the-line ticket",
"Professional guide",
"Headset"
],
"meetingPoint": {
"address": "Champ de Mars, Paris",
"latitude": 48.8584,
"longitude": 2.2945
},
"availableDates": [
"2025-06-15",
"2025-06-16",
"2025-06-17"
]
}
}
Search for wellness and spa experiences worldwide, including massages, thermal baths, yoga retreats, facials, and beauty treatments. Browse offerings by destination, date, and category.
/api/v1/wellness/search
Search for available wellness and spa experiences at a specific destination.
| Name | Type | Required | Description |
|---|---|---|---|
| city_code | string | Yes | City or destination code (e.g., BKK, DPS, IST). |
| date | string | No | Preferred appointment date in YYYY-MM-DD format. |
| category | string | No | Filter by category: spa_treatment, massage, facial, body_treatment, thermal_bath, hammam, yoga, meditation, fitness, wellness_retreat, detox. |
| adults | integer | No | Number of adult participants (1-9). Defaults to 1. |
| children | integer | No | Number of child participants (0-9). Defaults to 0. |
| currency | string | No | ISO 4217 currency code (e.g., USD, EUR). Defaults to USD. |
{
"data": [
{
"id": "wellness_abc123",
"name": "Traditional Thai Massage",
"description": "Authentic Thai massage experience in a serene spa setting.",
"image": "https:\/\/example.com\/images\/thai-massage.jpg",
"price": {
"amount": "85.00",
"currency": "USD"
},
"duration": "120 minutes",
"category": "massage",
"rating": 4.8,
"review_count": 342,
"free_cancellation": true,
"source": "manual"
}
],
"meta": {
"total": 24
}
}
/api/v1/wellness/{offerId}
Get detailed information about a specific wellness or spa experience, including amenities, inclusions, and booking details.
| Name | Type | Required | Description |
|---|---|---|---|
| offerId | string | Yes | The unique identifier of the wellness offer. |
{
"data": {
"id": "wellness_abc123",
"name": "Traditional Thai Massage",
"description": "Experience the art of traditional Thai massage in a peaceful spa environment.",
"images": [
"https:\/\/example.com\/images\/thai-massage-1.jpg",
"https:\/\/example.com\/images\/thai-massage-2.jpg"
],
"price": {
"amount": "85.00",
"currency": "USD",
"per_person": true
},
"duration": "120 minutes",
"duration_minutes": 120,
"category": "massage",
"rating": 4.8,
"review_count": 342,
"location": {
"city": "Bangkok",
"address": "123 Sukhumvit Road, Bangkok"
},
"highlights": [
"Certified therapists",
"Traditional techniques",
"Complimentary herbal tea"
],
"included": [
"Massage session",
"Herbal compress",
"Welcome drink"
],
"excluded": [
"Gratuities",
"Transportation"
],
"amenities": [
"sauna",
"steam_room",
"pool",
"relaxation_area"
],
"meeting_point": "123 Sukhumvit Road, Bangkok 10110",
"free_cancellation": true,
"cancellation_policy": "Free cancellation up to 24 hours before appointment."
}
}
Search for rental car availability, confirm pricing, and create car rental orders across pickup and drop-off locations worldwide.
/api/v1/cars/search
Search for available rental cars at a specific location and time range.
| Name | Type | Required | Description |
|---|---|---|---|
| pickup_code | string | Yes | Pickup location name or IATA code. |
| dropoff_code | string | No | Drop-off location. Same as pickup if omitted. |
| pickup_datetime | string | Yes | Pickup date and time in YYYY-MM-DDTHH:MM format. |
| return_datetime | string | Yes | Return date and time in YYYY-MM-DDTHH:MM format. |
| currency | string | No | ISO 4217 currency code (e.g., USD, EUR). |
| driver_age | integer | No | Driver age (18-99). Some providers require this. |
| car_type | string | No | Filter by car type (compact, sedan, suv, etc.). |
| transmission | string | No | Filter by transmission type (automatic, manual). |
{
"data": [
{
"id": "car_jkl345",
"vehicle": {
"make": "Toyota",
"model": "Corolla",
"year": 2024,
"category": "compact"
},
"supplier": "Hertz",
"price": {
"amount": "42.00",
"currency": "USD",
"perDay": true
},
"features": [
"automatic",
"air_conditioning",
"4_doors",
"5_seats"
],
"thumbnail": "https:\/\/example.com\/images\/car_jkl345.jpg"
}
],
"meta": {
"total": 31,
"currency": "USD"
}
}
/api/v1/cars/offers/{offerId}/price
Get confirmed, up-to-date pricing for a specific car rental offer. Always confirm pricing before creating an order.
| Name | Type | Required | Description |
|---|---|---|---|
| offerId | string | Yes | The unique identifier of the car rental offer. |
| provider | string | No | Provider name (e.g., expedia, manual). Defaults to expedia. |
{
"data": [
{
"id": "car_jkl345",
"vehicle": {
"make": "Toyota",
"model": "Corolla",
"category": "compact"
},
"price": {
"amount": "42.00",
"currency": "USD",
"perDay": true,
"totalAmount": "294.00"
},
"insurance": {
"included": true,
"type": "basic"
}
}
],
"meta": {
"priceValidUntil": "2025-06-15T12:00:00Z"
}
}
/api/v1/cars/orders
Create a car rental order from a confirmed offer. Requires cars:write scope.
| Name | Type | Required | Description |
|---|---|---|---|
| offer_id | string | Yes | The offer ID to book. |
| provider | string | Yes | Provider name: manual or expedia. |
| driver | object | No | Driver details (name, age, license info). |
| customer | object | No | Customer contact details (name, email, phone). |
| payment | object | No | Payment details. |
{
"data": {
"orderId": "car_order_xyz",
"status": "confirmed",
"vehicle": {
"make": "Toyota",
"model": "Corolla"
},
"pickup": {
"location": "JFK Airport",
"datetime": "2025-06-15T10:00:00"
},
"dropoff": {
"location": "JFK Airport",
"datetime": "2025-06-22T10:00:00"
},
"totalPrice": {
"amount": "294.00",
"currency": "USD"
}
}
}
Book airport transfers, city-to-city rides, and private car services. Create, retrieve, and cancel transfer orders.
/api/v1/transfers/orders
Create a transfer order for airport pickups, hotel transfers, or city-to-city rides.
| Name | Type | Required | Description |
|---|---|---|---|
| transfer_offer_id | string | Yes | The transfer offer ID to book. |
| travelers | array | Yes | Array of traveler objects with name and contact details. |
| customer | object | No | Customer contact information. |
| payment | object | No | Payment details. |
| provider | string | No | Provider name. Defaults to amadeus. |
{
"data": {
"id": "transfer_mno678",
"status": "confirmed",
"pickup": {
"address": "Charles de Gaulle Airport, Terminal 2E",
"time": "2025-06-15T14:00:00"
},
"dropoff": {
"address": "Grand Plaza Hotel, Paris"
},
"vehicle": {
"type": "sedan",
"maxPassengers": 3
},
"price": {
"amount": "55.00",
"currency": "USD"
},
"driver": {
"name": "Jean-Pierre",
"phone": "+33612345678"
}
}
}
/api/v1/transfers/orders/{orderId}
Retrieve details for a specific transfer order, including status, driver information, and vehicle details.
| Name | Type | Required | Description |
|---|---|---|---|
| orderId | string | Yes | The unique transfer order identifier. |
| provider | string | No | Provider name. Defaults to amadeus. |
{
"data": {
"id": "transfer_mno678",
"status": "confirmed",
"pickup": {
"address": "Charles de Gaulle Airport, Terminal 2E",
"time": "2025-06-15T14:00:00"
},
"dropoff": {
"address": "Grand Plaza Hotel, Paris"
},
"vehicle": {
"type": "sedan",
"maxPassengers": 3
},
"price": {
"amount": "55.00",
"currency": "USD"
},
"driver": {
"name": "Jean-Pierre",
"phone": "+33612345678"
}
}
}
/api/v1/transfers/orders/{orderId}
Cancel an existing transfer order. Subject to the cancellation policy of the provider.
| Name | Type | Required | Description |
|---|---|---|---|
| orderId | string | Yes | The unique transfer order identifier. |
| provider | string | No | Provider name. Defaults to amadeus. |
{
"data": {
"id": "transfer_mno678",
"status": "cancelled",
"cancelledAt": "2025-06-14T10:00:00Z"
}
}
Manage the complete booking lifecycle. Create bookings from flight, hotel, or other offers, list existing bookings, and handle cancellations.
/api/v1/bookings
Create a new booking from a confirmed offer. Accepts flight, hotel, rental, tour, car, or transfer offer IDs.
| Name | Type | Required | Description |
|---|---|---|---|
| offer_id | string | Yes | The offer ID to book (e.g., offer_abc123). |
| offer_type | string | Yes | Type of offer: flight, hotel, rental, tour, car, or transfer. |
| passengers | array | Yes | Array of passenger objects with name, email, and phone fields. |
| payment_method | string | Yes | Payment method identifier (e.g., stripe, paypal). |
{
"data": {
"id": "booking_pqr901",
"bookingNumber": "BK-20250615-ABC",
"status": "confirmed",
"offerType": "flight",
"totalPrice": {
"amount": "698.00",
"currency": "USD"
},
"createdAt": "2025-06-10T09:30:00Z"
}
}
/api/v1/bookings
List all bookings for the authenticated API key, with optional filtering and pagination.
| Name | Type | Required | Description |
|---|---|---|---|
| status | string | No | Filter by status: confirmed, pending, cancelled, completed. |
| page | integer | No | Page number for pagination. Defaults to 1. |
| per_page | integer | No | Results per page (10-100). Defaults to 15. |
{
"data": [
{
"id": "booking_pqr901",
"bookingNumber": "BK-20250615-ABC",
"status": "confirmed",
"offerType": "flight",
"totalPrice": {
"amount": "698.00",
"currency": "USD"
},
"createdAt": "2025-06-10T09:30:00Z"
}
],
"meta": {
"total": 12,
"page": 1,
"per_page": 15,
"last_page": 1
}
}
/api/v1/bookings/{bookingId}
Get full details for a specific booking, including traveler information and payment status.
| Name | Type | Required | Description |
|---|---|---|---|
| bookingId | string | Yes | The unique booking identifier or booking number. |
{
"data": {
"id": "booking_pqr901",
"bookingNumber": "BK-20250615-ABC",
"status": "confirmed",
"offerType": "flight",
"passengers": [
{
"name": "John Doe",
"email": "john@example.com"
}
],
"totalPrice": {
"amount": "698.00",
"currency": "USD"
},
"paymentStatus": "paid",
"createdAt": "2025-06-10T09:30:00Z"
}
}
/api/v1/bookings/{bookingId}/cancel
Request cancellation of an existing booking. Subject to the cancellation policy of the offer type.
| Name | Type | Required | Description |
|---|---|---|---|
| bookingId | string | Yes | The unique booking identifier. |
| reason | string | No | Optional reason for cancellation. |
{
"data": {
"id": "booking_pqr901",
"status": "cancelled",
"refund": {
"amount": "628.20",
"currency": "USD",
"status": "processing"
},
"cancelledAt": "2025-06-12T14:00:00Z"
}
}
Search for places, airports, and popular destinations. Use these endpoints to power search forms and autocomplete fields in your application.
/api/v1/places/search
Search for places by name or city. Returns locations with coordinates, ratings, and metadata.
| Name | Type | Required | Description |
|---|---|---|---|
| q | string | Yes | Search query string (minimum 1 character). |
| limit | integer | No | Maximum number of results (1-20). Defaults to 10. |
{
"data": [
{
"id": 1,
"name": "Eiffel Tower",
"city": "Paris",
"country": "FR",
"lat": 48.8584,
"lng": 2.2945,
"types": [
"tourist_attraction",
"landmark"
],
"rating": 4.7
}
]
}
/api/v1/places/airports
Search for airports by name or IATA code. Useful for powering flight search autocomplete fields.
| Name | Type | Required | Description |
|---|---|---|---|
| q | string | Yes | Search query (minimum 2 characters). Matches airport name, city, or IATA code. |
{
"data": [
{
"iata": "JFK",
"name": "John F. Kennedy International Airport",
"city": "New York",
"country": "US"
},
{
"iata": "LGA",
"name": "LaGuardia Airport",
"city": "New York",
"country": "US"
}
]
}
/api/v1/places/popular
Get popular destinations for a given travel module. Useful for showing trending locations on your homepage.
| Name | Type | Required | Description |
|---|---|---|---|
| type | string | No | Module type: flights, hotels, tours, rentals, cars, transfers. Defaults to flights. |
{
"data": [
{
"destination": "Paris",
"country": "FR",
"iata": "CDG",
"searchCount": 15420
},
{
"destination": "London",
"country": "GB",
"iata": "LHR",
"searchCount": 12890
},
{
"destination": "Tokyo",
"country": "JP",
"iata": "NRT",
"searchCount": 9780
}
]
}