Skip to content
tourpingotourpingotourpingo developers

Listing trips

The trip list

Section titled “The trip list”

GET /v1/public/products lists the site’s published trips, newest first, a page at a time. Each card has what a list needs: title, summary, cover photo, length, where it starts, its categories, its seller and its from_price.

The seller's trips, two at a time
Terminal window
curl "https://api.stg.vacationpackagesoman.com/v1/public/products?limit=2&locale=en" \
  -H "Tp-Publishable-Key: $TP_KEY"
Answer: 200 OK (shortened)
{
  "data": [
    {
      "id": "5b1f0c3e-8d2a-4f6b-9c41-2e7a9d0b6f13",
      "slug": "desert-safari-with-bbq-dinner",
      "template": "day_tour",
      "content_locale": "en",
      "title": "Desert safari with BBQ dinner",
      "summary": "Dune driving in a 4WD, a camel ride and dinner at a desert camp outside Dubai.",
      "duration_minutes": 360,
      "duration_days": null,
      "duration_nights": null,
      "sales_paused": false,
      "cover": {
        "url": "https://api.stg.vacationpackagesoman.com/media/dubai-safari.jpg",
        "alt": "4WDs on the dunes outside Dubai"
      },
      "city": {
        "slug": "dubai",
        "name": "Dubai"
      },
      "region": {
        "slug": "dubai-emirate",
        "name": "Dubai"
      },
      "country": {
        "slug": "ae",
        "name": "United Arab Emirates"
      },
      "categories": [
        {
          "slug": "desert-safari",
          "name": "Desert & Safari"
        }
      ],
      "seller": {
        "slug": "demo",
        "name": "tourpingo demo"
      },
      "from_price": {
        "amount": 6500,
        "currency": "USD",
        "group_size": 1
      }
    },
    {
      "id": "6c2a1d4f-9e3b-4a7c-8d52-3f8b0e1c7a24",
      "slug": "abu-dhabi-city-tour-full-day",
      "template": "day_tour",
      "content_locale": "en",
      "title": "Abu Dhabi city tour, full day",
      "summary": "The Sheikh Zayed Grand Mosque, the Corniche and Qasr Al Watan in one day.",
      "duration_minutes": 600,
      "duration_days": null,
      "duration_nights": null,
      "sales_paused": false,
      "cover": {
        "url": "https://api.stg.vacationpackagesoman.com/media/abu-dhabi.jpg",
        "alt": "Sheikh Zayed Grand Mosque, Abu Dhabi"
      },
      "city": {
        "slug": "abu-dhabi",
        "name": "Abu Dhabi"
      },
      "region": {
        "slug": "abu-dhabi-emirate",
        "name": "Abu Dhabi"
      },
      "country": {
        "slug": "ae",
        "name": "United Arab Emirates"
      },
      "categories": [
        {
          "slug": "city-tours",
          "name": "City Tours"
        }
      ],
      "seller": {
        "slug": "demo",
        "name": "tourpingo demo"
      },
      "from_price": null
    }
  ],
  "next_cursor": "WyIyMDI2LTA5LTI0VDExOjIwOjAwLjAwMFoiLCI2YzJhMWQ0Zi05ZTNiLTRhN2MtOGQ1Mi0zZjhiMGUxYzdhMjQiXQ",
  "total": 4
}

Filter with any of these, combined:

Parameter Takes
city, region, place Slugs, e.g. city=dubai. A place matches trips that start there or visit it.
country Country codes, e.g. country=ae,om.
category Category slugs, e.g. desert-safari.
template day_tour, multi_day, transfer, ticket or activity.
duration up_to_3h, 3h_to_6h, full_day or multi_day.
seller On a marketplace, sellers’ slugs, e.g. dft,voa.
q What the traveller typed. Typos are forgiven, and the best matches come first.
price shown for trips with a from_price, ask for those without.
travellers A group size: each card then has group_price, what that many pay.
max_price The most one traveller pays, in the currency’s minor units.
sort recommended (the default: the best matches for q first, else the newest), price, rating or duration.
facets true to count, for each filter, how many trips each value would show.
currency, locale The currency for prices, and the language for text.

Most take several values, comma-separated.

total is how many trips match. Page through them with next_cursor, as pagination shows.

Section titled “Search”

GET /v1/public/search matches words and forgives typos, so “dessert safari” finds the desert safari. It pages by number (page, per_page) and counts facets as it goes.

Search, forgiving typos
Terminal window
curl "https://api.stg.vacationpackagesoman.com/v1/public/search?q=dessert%20safari&locale=en&per_page=10" \
  -H "Tp-Publishable-Key: $TP_KEY"
Answer: 200 OK (shortened)
{
  "data": [
    {
      "template": "day_tour",
      "content_locale": "en",
      "sales_paused": false,
      "duration_days": null,
      "duration_nights": null,
      "id": "5b1f0c3e-8d2a-4f6b-9c41-2e7a9d0b6f13",
      "slug": "desert-safari-with-bbq-dinner",
      "title": "Desert safari with BBQ dinner",
      "duration_minutes": 360,
      "city": {
        "slug": "dubai",
        "name": "Dubai"
      },
      "region": {
        "slug": "dubai-emirate",
        "name": "Dubai"
      },
      "country": {
        "slug": "ae",
        "name": "United Arab Emirates"
      },
      "seller": {
        "slug": "demo",
        "name": "tourpingo demo"
      },
      "from_price": {
        "amount": 6500,
        "currency": "USD",
        "group_size": 1
      }
    }
  ],
  "total": 1,
  "page": 1,
  "facets": {
    "city": [
      {
        "value": "dubai",
        "name": "Dubai",
        "count": 1
      }
    ],
    "category": [
      {
        "value": "desert-safari",
        "name": "Desert & Safari",
        "count": 1
      }
    ],
    "template": [
      {
        "value": "day_tour",
        "name": null,
        "count": 1
      }
    ],
    "duration": [
      {
        "value": "3h_to_6h",
        "name": null,
        "count": 1
      }
    ]
  }
}

When the search index is down, search answers 503 SearchUnavailable, never an empty list. Fall back to the trip list with q.

What to filter by

Section titled “What to filter by”

These list only what the site’s published trips use, named in locale when translated:

  • GET /v1/public/cities: where trips start, with their region, country and trip_count.
  • GET /v1/public/categories: the platform’s categories, in its order, with their trip_count.
  • GET /v1/public/places: places trips start at or visit, such as a wadi or a fort; GET /v1/public/places/{place} has one place’s page.
  • GET /v1/public/sellers: the sellers, with where each is based.

Show the seller

Section titled “Show the seller”

Name the seller on every card and trip page, from the trip’s seller, so travellers know who runs the trip.