Quickstart

Get up and running with the Requirements API in minutes.

What you'll build

In this quickstart, you'll learn how to make a simple API call to the /v3/trips endpoint and display travel requirements in a basic HTML page. We'll show you how to:

Set up your API request
Handle the response data
Display travel requirements in a clean, readable format

Prerequisites

Before you start, you'll need:

An API key from Sherpa (get API access)
Basic knowledge of HTML and JavaScript
A web server or local development environment

Step 1: Make your first API call

Let's start with a simple trip from the United States to the United Kingdom. Here's the basic request structure:

// Set up your API request
const apiKey = 'YOUR_API_KEY_HERE';
// Include restriction and procedure details in the response
const apiUrl =
  'https://requirements-api.joinsherpa.com/v3/trips?include=restriction,procedure';

const requestData = {
  data: {
    type: 'TRIP',
    attributes: {
      locale: 'en-US',
      traveller: {
        passports: ['USA'],
      },
      currency: 'USD',
      travelNodes: [
        {
          type: 'ORIGIN',
          locationCode: 'USA',
          departure: {
            date: '2026-06-15',
            time: '10:00',
            travelMode: 'AIR',
          },
        },
        {
          type: 'DESTINATION',
          locationCode: 'GBR',
          arrival: {
            date: '2026-06-15',
            time: '14:30',
            travelMode: 'AIR',
            flightNumber: 'BA1234',
          },
        },
      ],
    },
  },
};

// Make the API call
fetch(apiUrl, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/vnd.api+json',
    'x-api-key': apiKey,
  },
  body: JSON.stringify(requestData),
})
  .then((response) => response.json())
  .then((data) => {
    console.log('API Response:', data);
    displayTravelRequirements(data);
  })
  .catch((error) => {
    console.error('Error:', error);
  });

🔑 API Key Security

Never expose your API key in client-side code. In production, make API calls from your backend server and use environment variables to store your API key securely.

Step 2: Understanding the response

The API returns a structured response with travel requirements organized into information groups. The exact structure depends on your API key and the specific trip details. Here's what a complete response structure looks like:

{
  "meta": {
    "copyright": "Sherpa",
    "version": "3.0.2"
  },
  "data": {
    "id": "1eab7e7f-d2be-4ddb-910f-e6713cb76147",
    "type": "TRIP",
    "attributes": {
      "headline": "Most travelers from United States can enter United Kingdom. See below for visa and travel requirements.",
      "locale": "en-US",
      "traveller": {
        "passports": ["USA"],
        "vaccinations": [
          {
            "type": "COVID_19",
            "status": "NOT_VACCINATED"
          }
        ]
      },
      "currency": "USD",
      "travelNodes": [
        {
          "type": "ORIGIN",
          "locationCode": "USA",
          "locationName": "United States",
          "departure": {
            "date": "2026-06-15",
            "time": "10:00",
            "travelMode": "AIR"
          }
        },
        {
          "type": "DESTINATION",
          "locationCode": "GBR",
          "locationName": "United Kingdom",
          "arrival": {
            "date": "2026-06-15",
            "time": "14:30",
            "travelMode": "AIR",
            "flightNumber": "BA1234"
          }
        }
      ],
      "informationGroups": [
        {
          "name": "Visa Requirements",
          "type": "VISA_REQUIREMENTS",
          "tooltip": "Visa requirements are determined by the passport you are travelling with and duration of your trip.",
          "groupings": [
            {
              "name": "United Kingdom",
              "enforcement": "MANDATORY",
              "data": [
                {
                  "type": "PROCEDURE",
                  "id": "fc017417-4c0d-4ec3-aae7-a2cfd9f2ba3c"
                }
              ]
            }
          ],
          "enforcement": "MANDATORY",
          "headline": "You need an ETA for United Kingdom if you have a United States passport."
        }
      ],
      "travelOpenness": "LEVEL_1"
    }
  },
  "included": [
    {
      "id": "fc017417-4c0d-4ec3-aae7-a2cfd9f2ba3c",
      "type": "PROCEDURE",
      "attributes": {
        "title": "Electronic travel authorization",
        "description": "Travelers visiting the UK for under six months require an Electronic Travel Authorization (ETA).",
        "enforcement": "MANDATORY",
        "actions": [
          {
            "type": "LINK",
            "title": "Apply online",
            "url": "https://sherpa-widget.joinsherpa.io/applications/products/GBR_ETA__GROUPA",
            "provider": "sherpa",
            "intent": "apply-product",
            "product": {
              "name": "United Kingdom eTA",
              "price": {
                "value": 31.21,
                "currency": "USD"
              },
              "times": {
                "applicationDeadline": {
                  "type": "HOURS",
                  "value": 24,
                  "text": "24 hours"
                }
              }
            }
          }
        ],
        "sources": [
          {
            "type": "GOVERNMENT",
            "title": "Government of United Kingdom",
            "url": "https://www.gov.uk/check-uk-visa"
          }
        ],
        "documentTypes": ["ETA"],
        "lengthOfStay": [
          {
            "type": "DAYS",
            "value": 180,
            "text": "180 days"
          }
        ]
      }
    }
  ]
}

📋 Response Variations

The API response structure can vary depending on your API key type and the specific trip. Some responses may include detailed informationGroups with requirements, while others might return a simpler structure with just the trip details. The HTML example below handles both cases gracefully.

Step 3: Display the results

Now let's create a simple HTML page that displays the travel requirements. This example shows the basic structure for parsing and displaying the API response:

Key concepts:

Use optional chaining (?.) to safely access nested properties
Loop through informationGroups to display different requirement categories
Find detailed requirements in the included array using the requirement ID
Display actions as clickable links with pricing information

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Travel Requirements - Quickstart</title>
  </head>
  <body>
    <h1>Travel Requirements</h1>
    <div id="trip-summary"></div>
    <div id="requirements"></div>

    <script>
      // Your API configuration
      const API_KEY = 'YOUR_API_KEY_HERE';
      const API_URL =
        'https://requirements-api.sandbox.joinsherpa.com/v3/trips?include=restriction,procedure';

      // Trip data
      const tripData = {
        data: {
          type: 'TRIP',
          attributes: {
            locale: 'en-US',
            traveller: {
              passports: ['USA'],
            },
            currency: 'USD',
            travelNodes: [
              {
                type: 'ORIGIN',
                locationCode: 'USA',
                departure: {
                  date: '2026-06-15',
                  time: '10:00',
                  travelMode: 'AIR',
                },
              },
              {
                type: 'DESTINATION',
                locationCode: 'GBR',
                arrival: {
                  date: '2026-06-15',
                  time: '14:30',
                  travelMode: 'AIR',
                  flightNumber: 'BA1234',
                },
              },
            ],
          },
        },
      };

      // Function to display travel requirements
      function displayTravelRequirements(response) {
        const tripSummary = document.getElementById('trip-summary');
        const requirements = document.getElementById('requirements');

        // Display the headline
        const headline =
          response.data?.attributes?.headline || 'Travel Requirements';
        tripSummary.innerHTML = `<h2>${headline}</h2>`;

        // Display trip details
        const travelNodes = response.data?.attributes?.travelNodes || [];
        if (travelNodes.length > 0) {
          const tripDetails = document.createElement('div');
          tripDetails.innerHTML = '<h3>Trip Details</h3>';

          travelNodes.forEach((node) => {
            const location =
              node.locationName || node.locationCode || 'Unknown';
            const details = `
                        <p><strong>${node.type}:</strong> ${location}</p>
                        ${node.departure ? `<p>Departure: ${node.departure.date} at ${node.departure.time}</p>` : ''}
                        ${node.arrival ? `<p>Arrival: ${node.arrival.date} at ${node.arrival.time}</p>` : ''}
                    `;
            tripDetails.innerHTML += details;
          });

          requirements.appendChild(tripDetails);
        }

        // Display requirements
        const informationGroups =
          response.data?.attributes?.informationGroups || [];
        informationGroups.forEach((group) => {
          const groupElement = document.createElement('div');
          groupElement.innerHTML = `<h3>${group.name}</h3>`;

          group.groupings?.forEach((grouping) => {
            const groupingElement = document.createElement('div');
            groupingElement.innerHTML = `<h4>${grouping.name}</h4>`;

            // Find detailed requirements in the included array
            const requirementsList = document.createElement('ul');
            grouping.data?.forEach((requirement) => {
              const detailed = response.included?.find(
                (item) => item.id === requirement.id,
              );
              if (detailed?.attributes) {
                const listItem = document.createElement('li');
                listItem.innerHTML = `
                                <strong>${detailed.attributes.title}</strong>
                                <p>${detailed.attributes.description}</p>
                                <p><em>Status: ${detailed.attributes.enforcement}</em></p>
                                ${displayActions(detailed.attributes.actions)}
                            `;
                requirementsList.appendChild(listItem);
              }
            });

            groupingElement.appendChild(requirementsList);
            groupElement.appendChild(groupingElement);
          });

          requirements.appendChild(groupElement);
        });
      }

      // Helper function to display actions
      function displayActions(actions) {
        if (!actions || actions.length === 0) return '';

        let actionsHtml = '<div><strong>Actions:</strong><ul>';
        actions.forEach((action) => {
          actionsHtml += `<li><a href="${action.url}" target="_blank">${action.title}</a>`;
          if (action.product?.price) {
            actionsHtml += ` (${action.product.price.currency} ${action.product.price.value})`;
          }
          actionsHtml += '</li>';
        });
        actionsHtml += '</ul></div>';

        return actionsHtml;
      }

      // Make the API call when page loads
      fetch(API_URL, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/vnd.api+json',
          'x-api-key': API_KEY,
        },
        body: JSON.stringify(tripData),
      })
        .then((response) => {
          if (!response.ok) {
            throw new Error(`HTTP error! status: ${response.status}`);
          }
          return response.json();
        })
        .then((data) => {
          displayTravelRequirements(data);
        })
        .catch((error) => {
          console.error('Error fetching travel requirements:', error);
          document.getElementById('requirements').innerHTML =
            '<p>Error loading travel requirements. Please check your API key and try again.</p>';
        });
    </script>
  </body>
</html>

Here's what the rendered result looks like:

Basic API Response Display

Understanding the response structure

The API response contains several key sections:

Trip Summary

headline: A human-readable summary of the trip requirements
traveller: Information about the traveler's passport and vaccination status
travelNodes: Details about the trip itinerary

Information Groups

Travel requirements are organized into categories:

Visa Requirements: Entry visa and documentation needs
Travel Restrictions: Any travel bans or limitations
Public Health Requirements: COVID-19 testing, vaccination, quarantine rules
Documents and Forms: Required paperwork and applications
Additional Information: Other important travel details

Enforcement Levels

Each requirement has an enforcement level:

MANDATORY: Required for travel
NOT_REQUIRED: Not needed
MAY_BE_REQUIRED: Depends on specific circumstances

#Quickstart

#What you'll build

#Prerequisites

#Step 1: Make your first API call

#Step 2: Understanding the response

#Step 3: Display the results

#Understanding the response structure

#Trip Summary

#Information Groups

#Enforcement Levels