README.md

Alpaca Travel GraphQL API

The Alpaca Travel GraphQL API provides developers with easy access to the platform's itinerary content for use in interactive applications and user interfaces.

• Easily access and manipulate itinerary data through a GraphQL API

• Incorporate platform's itinerary content into custom interactive applications and user interfaces such as travel itinerary planners and trip planning websites.

• Retrieve and display itinerary information, including maps, routes, places and uploaded content, in desired format.

• Engage with your audience and offer personalized travel experience by providing basic itinerary planning features.

• Convenient tool for including platform's itinerary content in your project, and for providing your users the ability to create and update itineraries.

The Alpaca Travel platform supports a wide range of itineraries, including:

• Road-trips

• Walking and hiking trails

• Flights and other modes of transportation

• Top-10 lists and other types of curated content

The Alpaca Travel platform offers more than just itinerary management, it also includes features such as guide and directory creation, location search and place information loading to enhance the functionality of your travel-related application or website.

Documentation Overview

The Alpaca Travel Platform is accessed using GraphQL, a powerful and easily integrated techology for your website or application. You can read some supporting information on GraphQL and why it is used below.

• Getting Started Starting guides for developers around the Alpaca Travel GraphQL API.

• Example Operations We have put together concrete examples of typical calls to the API in our example operations section. These will assist you become familiar with GraphQL as well as the capabilities of the platform.

• Example Applications We have provided some working examples of apps for you to play and adapt that demonstrates the technology in use.

• Mapping In addition to the GraphQL API, we also provide hosted mapping services for accessing and presenting data on maps. You can access these services by visiting our mapping documentation for more information.

GraphQL Endpoint

In order to interact with the Alpaca Travel API, you will need to use GraphQL. The GraphQL endpoint for the Alpaca Travel API is:

https://graphql.withalpaca.travel/?accessToken=<YOUR_API_KEY>

When using the root endpoint, it is important to authenticate via providing your accessToken (which is your API Key) as a query parameter.

• Token Authorization Understand more about Alpaca Travel API Keys and Tokens

• GraphQL Topics Getting started with GraphQL

• Apollo Sandbox Use the GraphQL Sandbox in order to explore and execute queries and mutations against the Alpaca GraphQL API from your web browser

• Schema Reference Generated documentation based on the Alpaca Travel GraphQL Scheme to assist with understanding data types and operations

Getting Started

Itinerary

If you are new to the Alpaca Travel GraphQL API, we have created a series of guides that can familiarize you with the GraphQL API based on some common starting points developers have.

We recommend you start with the following guides to familiarize yourself with the queries and mutations available with the GraphQL API

• Reading from Itineraries Read and access content from itineraries created on the Alpaca Platform

• Managing a List Create, update and manage a curated list of locations for users

• Managing a Trip Create and manage a trip with routes and directions between locations

• Example Itinerary Operations A series of GraphQL documents that provide examples for working with itinerary operations

• Specific Topics Specific reference topics for working with itineraries

Collections

Collections support the ability to create groups of places or itineraries to power your website or application.

• Working with Collections Understand how to manage collections and your place library

• Example Collection Operations A series of GraphQL documents that provide examples for working with collection and collection location operations

Places / Place Information

We support working with various place providers on the platform, to access place information and keep your place information up to date.

• Working with Places Understand how to work with places on Alpaca, including integration with various place provides such as OSM, Australian Tourism Data Warehouse (ATDW), and Facebook Pages. Learn how to access opening hours or other place attributes.

Other References

• GraphQL Topics Get started with GraphQL and understand some specific related topics

• Example Operations Example operations across the full Alpaca Travel GraphQL API

• Working with Media Upload media and query media to display in your application or website

• Working with Positions Access global information about a position, such as region, time-zone or ISO data, or local data such as information about a location from the ABS dataset

• Working with Icons Manage profile icons sets and associate them with Itineraries

JavaScript

Any GraphQL client can be used with JavaScript but the below guides may assist you getting started with JavaScript.

• References Examples of displaying content in the browser

• Making GraphQL Calls Simple methods for executing GraphQL using JavaScript

• React Apollo Client Get started with React and Apollo Client to access an itinerary

• Alpaca GraphQL JavaScript SDK (New) SDKs based on popular JavaScript development environments, including React, Vue, Svelte and Stencil. The SDK provides options for developers such as leveraging urql, graphql-request, react-query and apollo.

Example Applications

We have included some example stand-alone code that you can use to build upon in order to display content from the Alpaca Travel service.

These are provided as working examples you can modify for your own uses.

• Browser Examples We have some examples of interactive maps that display in your browser.

• React/Apollo Load Itinerary Simple example of a react application loading an itinerary using the "itinerary" operation.

• React Place Slider Example loading a "slider" of location cards from a collection pulling in information from Australian Tourism Data Warehouse (ATDW). You can customise and run this in browser as a demo (code sandbox).

• React Opening Hours Example loading of a place opening hours, demonstrating some presentation of current status or schedule for a series of dates.

More examples to come

Example Operations

A catalogue of example GraphQL queries and mutations are provided as example gists for you to refer to for specific functionality.

Support 👍

Alpaca Travel offers support for API clients. Clients are provided access to Basecamp to manage integration projects, or alternatively questions can be directed to sayhello@alpaca.travel.

Contributing

We are happy to accept pull-requests, suggestions and corrections.

We have quality control mechanisms to assist in keeping the documentation is kept maintained. This includes GitHub actions to validate site links as well as valid GraphQL examples (in both .graphql files and featuring in markdown).

Sections such as the reference is managed external to this repository and can't be changed. In that case, please describe the change to us in an Issue, and we will resolve.

Quick Edits

You can make quick edits through GitHub by using the pencil ✏️ edit process and submit a pull request.

Further Edits

Alternatively, you can pull down the git repo to make your changes. You can check your changes by using the following commands:

npm i
npm test

Note: This documentation package is validated against GraphQL and we check to make sure we don't have dead links. Please check against mistakes using npm test above.

Legal Statement

Copyright © 2020-2022 Alpaca Travel. All rights reserved.

Please be aware that use of this API is subject to an services agreement with Alpaca Travel.