NAV
http

Introduction

Welcome to the Magpie API, which provides programmatic access to the Magpie platform.

Authentication

Provide X-Api-Key header:

GET /api HTTP/1.1
Host: magpie.travel
Accept: application/json
X-Api-Key: 58c068808359e091c310054e43c3c27a

or api_key query parameter:

GET /api?api_key=58c068808359e091c310054e43c3c27a HTTP/1.1
Host: magpie.travel
Accept: application/json
HTTP/1.1 200 OK
Content-Type: application/json

{ "documentation": "https://docs.magpie.travel" }

Magpie API requires the X-Api-Key header containing your API key to be included for all requests:

X-Api-Key: <Your API Key>

Alternatively, the API key can be provided via the api_key query parameter:

https://magpie.travel/api?api_key=<Your API Key>

If an API key was not given or it doesn't belong to an existing account, a 401 Unauthorized response status is returned.

You can find the API key for your Magpie account here.

Products

The Product resource consists of the following fields:

Attribute Type Description
id string The unique identifier of the product.
name string The name of the product.
internal_id string The user-defined internal ID of the product.
account object Contains name and username of the company account owning the product.
system_providers array List of product's system providers.
location string Custom location name of the product.
category string The product category.
duration string Duration of the product with unit.
currency string Currency used for the product.
language string Language used for the product.
timezone string Time zone in which the product is held.
higlights array Main features of the product.
summary string Short summary of the product.
description string Longer description of the product.
included string Features included in the product.
excluded string Features not incuded in the product.
before_booking string Important information people need to know before booking.
before_arrival string Important information people need to know before arrival.
additional_info string Any additional information for the product.
start_date date The date when the product starts.
end_date date The date when the product ends.

Get All Products

GET /api/products HTTP/1.1
Host: magpie.travel
Accept: application/json
X-Api-Key: 58c068808359e091c310054e43c3c27a
HTTP/1.1 200 OK
Content-Type: application/json

{
  "categories": [ ... ]
    "Air, Balloon & Helicopter Tours",
    "Attractions / Museums",
    ...
  ],
  "locations": [
    "1206 Front St, Sacramento, CA",
    "13755 Fiji Way, Marina del Rey, CA 90292",
    "207 Queens Quay W, Toronto, ON M5J 1A7, Canada",
    ...
  ],
  "limit_value": 100,
  "total_pages": 10,
  "current_page": 1,
  "next_page": 2,
  "prev_page": null,
  "products": [
    {
      "id": "3bba0442-7f76-4af2-8f90-a962a36833e8",
      "name": "Activity Private Xmas Markets & Alsace Villages",
      "internal_id": "55MJ4Q",
      "account": { "name": "Ophorus Tours in France", "username": "Ophorus" },
      "system_providers": [],
      "location": "Strasbourg",
      "category": "Tours & Sightseeing",
      "duration": "7 hours",
      "currency": "EUR",
      "language": "en",
      "timezone": "Europe/Paris",
      "highlights": [
        "Visit the famous markets of Colmar, knowledgeably guided by one of our local team.",
        "Visit Christmas markets in local villages along the Alsace Wine Route. ",
        ...
      ],
      "summary": "<div>Let us guide you through the most beautiful Alsatian villages and discover the wonders on Christmas markets in Alsace. Your suited private driver will drive you the whole day to places you want to explore. The tour is 100% tailor made and you can either visit the villages or experience a wine tasting in a typical winery.</div>",
      "description": "",
      "commentaries": [ "English: Guide", "French: Guide" ],
      "included": [
        "Visit Christmas markets in Colmar.",
        "English-speaking private driver & guide.",
        ...
      ],
      "excluded": [
        "Personal insurance and expenses.",
        "Meals & drinks.",
        ...
      ],
      "before_booking": [
        "Tour requires minimum 2 passengers (adults) to operate.",
        "Tour is operated in English, other languages on request.",
        ...
      ],
      "before_arrival": [
        "Tour involves some walking, comfortable walking shoes are recommended.",
        "Notify tour operator your Strasbourg hotel information as soon as receive confirmation. "
        ...
      ],
      "additional_info": "<div>Christmas market tour for 2 guests or a total of 8 guests, same party, in the private minivan. <br>Tour runs from 9:30am to 4:30pm, every day.<br>November 30th through December 23rd, 2019</div>",
      "restrictions": [ "Dresscode: Wear Warm Layered Clothing And Good Walking Shoes.", ... ],
      "start_date": null,
      "end_date": null,
      "booking_cutoff": [ 7, "days" ],
      "booking_min_pax": 2,
      "booking_max_pax": 8,
      "valid_for": "7 hours Only on date on reservation",
      "opening_hours": { "Sunday": "Closed", "Monday": "Open", "Tuesday": "Open", ... },
      "availability_notes": [ ],
      "addresses": [{ "location_type": "Starts", "directions": null, "notes": "Pick-up from your centrally located Strasbourg hotel.", "coordinates": "", "full_street_address": "Strasbourg, Alsace, FR" }],
      "cancellation_policy": "custom",
      "cancellation_cutoff": "7 days",
      "cancellation_notes": "Operator strictly adheres to its cancellation policy and will make no exceptions to the policy. If Guest chooses to cancel his or her reservation, ...",
      "terms_and_conditions": "Protection of personal data\r\n\r\nNCDK – OPHORUS attaches great importance to respecting the right to privacy. The policy on the protection of individuals ...",
      "voucher_info": "Notify tour operator your Strasbourg hotel information as soon as receive confirmation. ",
      "faqs": [],
      "confirmation_necessary": false,
      "redemption_type": "voucher | Evoucher"
    },
    ...
  ]
}

The /api/products endpoint returns a paginated list of all active products on Magpie. The following query parameters are accepted:

Parameter Default Description
page 1 The page to fetch.
limit 100 How many products should be retrieved per page.
location none The location to retrieve products for.
account none The username of the company account to retrieve products for.

The HTTP response will also include:

HTTP Request

GET https://magpie.travel/api/products
GET https://magpie.travel/api/products?page=2
GET https://magpie.travel/api/products?limit=50
GET https://magpie.travel/api/products?location=San%20Francisco
GET https://magpie.travel/api/products?account=Ophorus

Glossary

OCTo defines core terms that are re-used throughout the specification. A full description of those terms can be found on OCTo Spec Website but we have included a table below to get started.

Name Description
Reseller You are the reseller, connecting via the API
Supplier The supplier on Magpie which you are connecting to
Product The attraction, activity or tour
Option A variant of the product, all products must have at least one option
Unit The ticket type, e.g. Adult, Child, Senior etc.
Booking A booking made for a specific product and option and one or more unit items
Unit Item A line item per unit within the booking
Voucher A single barcode that can be used for the whole booking
Ticket A barcode that can be used per unit item