Sparky Tours API
The journeys an organization offers on its website, with their places, departures, booking terms and business profile.
- Address
- https://tours.sparkyli.com/api/v1
- Plan
- Plus and Max, with API access switched on for the organization
- Specification
- https://tours.sparkyli.com/api/v1/openapi.yaml
Endpoints
GET /tours
Tours flagged "Show on website", with length, from-price and the places each visits.
Inputs
| Name | Type | What it is |
|---|---|---|
| limit, offset | whole numbers | Paging: limit 1 to 100 (default 50); offset from next_offset. |
Answer: tours (a list) and next_offset
| Name | Type | What it is |
|---|---|---|
| id, title | text | The tour and its name. |
| summary, destination | text or null | |
| cities | list of text | The places the itinerary visits, in order, each once. Empty until the itinerary has places. |
| duration_days | whole number or null | |
| tags | list of text | |
| overseas | true or false | |
| from_price | object or null | amount (minor units, such as paise or cents) and currency. null means price on request. |
GET /tours/{id}
One tour, with its highlights and day list.
Inputs
| Name | Type | What it is |
|---|---|---|
| id* | text | The tour's id. |
Answer: tour
| Name | Type | What it is |
|---|---|---|
| (all the list fields, and these) | ||
| highlights | text or null | |
| days | list | One per day: day (number), title, theme and rest_day (true or false). |
Errors (besides the common ones)
- 404 not_found: No such tour, or it is not shown on the website.
GET /departures
Upcoming departures flagged for the website.
Inputs
| Name | Type | What it is |
|---|---|---|
| from | date, YYYY-MM-DD | Earliest departure date. Default today. |
| to | date, YYYY-MM-DD | Latest departure date. |
| limit, offset | whole numbers | Paging, as for tours. |
Answer: departures (a list) and next_offset
| Name | Type | What it is |
|---|---|---|
| id, tour_id, title | text | The departure, its tour and the tour's name. |
| destination | text or null | |
| departs_on, returns_on | date | |
| price_per_person | object or null | amount in minor units, and currency. |
| availability | open, few_left or full | A bucket. Seat counts are never shown. |
GET /business-profile
The organization's public business profile and the registrations it chose to show.
Answer: (top level)
| Name | Type | What it is |
|---|---|---|
| trade_name, legal_name, country, registered_address | text or null | As entered in the business profile. |
| tax_registration | object or null | The primary registration: type and number. |
| registrations | list | Only the ones the owner chose to show: type, number, issued_by and valid_until. |
| contacts | list | Contacts marked for the website: label, name, email and phone. |
GET /booking-terms
Booking amount, advance and balance rules, refund steps and whether online payment is ready.
Answer: (top level)
| Name | Type | What it is |
|---|---|---|
| online_payment | true or false | True when the organization's payment gateway is saved and switched on, so a "pay the booking amount" button can really work. |
| booking_amount | object | amount (minor units), currency, refundable and counted_toward_price. |
| advance | list | The advance by how early a customer books: advance_pct, with booked_at_least_days_before, or on the last row booked_fewer_than_days_before. |
| balance_due_days_before_departure | whole number | When the rest is due. |
| cancellation | list | Refund steps: within_days_of_departure and refund_pct. |
Example
curl -s -H "authorization: Bearer $TOKEN" -H "x-sparky-org: ORG_ID" https://tours.sparkyli.com/api/v1/toursNew here? Start with the three things first, then sign in. Errors are explained under errors and limits.