Integration

Access Tokens

The alpaca platform is accessible through creating Access Tokens to profiles. There are predominantly 2-levels of access tokens available, such as using a public or secret access token.

• public access tokens can be used for reading from a profile and performing basic functionality such as creating pseudo-anonymous itineraries
• secret access tokens are available for back-end write use-cases where the token will not be exposed publicly

Access Tokens are used across requests to various services available on the alpaca.tech platform. They are associated to profiles and have a scope for what they can perform.

Alpaca ID's

All content in the Alpaca platform are addressable by ID's. To quickly illustrate the structure of the Alpaca ID's, you can anticipate the following:

• Itinerary are referenced through an ID like itinerary/XXX
• Profile are referenced through an ID like profile/XXX

ID's are accessible either through the API or via the Itinerary Editor interface.

• Authorized Profiles Example API operation to obtain the profile ID associated with an access token

Profile Content

You can list content associated with a profile through the use of your public access token. In order for them to be visible, the content creator needs to have the content published and mark the content as discoverable.

You can leave content unlisted on the platform so that it is not discoverable.

Once content is successfully published, you will be able to obtain a list of the itineraries through the operation itineraries available through the API.

• List Itineraries Example API operation to list the itineraries that are published and discoverable

Using tags or other classifications, content could be filtered and displayed shown to users in an itineraries section.

By using the secret access token, you can view drafts and unlisted content.

Front-end Presentation

The alpaca.tech stack is designed to provide the same tools and API features that are used within the Itinerary Editor and off-the-shelf embeds to allow designers and developers full access to capabilities.

While all the alpaca.tech infrastructure is available to build your own products and designs, we also offer simple embeds and widgets as well as data sets (such as Vector Tile Hosting) to support quickly presenting information on a map.

Custom User Interfaces

Alpaca provides all the tools for designers and developers to be able to create their own user-experience with their own designs.

• The GraphQL API can provide access to query the structure and content of itineraries and associated place data. The API also provides a number of additional features, such as searching for places or directions.
• The Mapping services provide data formats to work with all types of mapping clients (such as Mapbox, MapLibre, Google, ESRI, HERE, Leaflet, etc)

The alpaca.tech stack can provide all the related services to build upon your interface to also allow the user plan their itinerary with search, routing and more.

• Querying an Itinerary through the API A getting started guide to understand how to use the API for reading in an itinerary in order to display it in your application.
• Creating Itineraries Develop applications around creating itineraries (such as a curated list of places like favourites, or full trip planning with full routes)

Embeds, and Widgets

Alpaca also offers some off the shelf embeds that allow developers to quickly leverage iframes and script tags in order to present itineraries on their website. This is an off-the-shelf approach, but has limited customisation to the presentation of the content.

Place Data

Alpaca is able to reference popular place data providers to load in additional information. This allows the information to be automatically joined on to your itineraries.

Place Providers:

• Open Data Providers: Alpaca supports a number of open data ID's that users can search and add to their itineraries, including OpenStreetMap, OpenAddresses, Who's On First and Geonames. These capture a wide range of venue and place data.
• National Data Providers: National data providers can provide access to place data, such as the Australian Tourism Data Warehouse.
• Commercial Place Providers: Alpaca supports large-scale place providers that can be referenced for their place data. This includes services such as Facebook, TripAdvisor, Foursquare and Yelp. These are managed by commercial arrangements with those providers.

3rd Party Place Providers:

• Place Libraries: Store and sync your place data on to an Alpaca collection, allowing you to display and load information about your places on the Alpaca platform.
• Custom Attributes: Use external IDs that link to your own place identifiers. While this does not allow you to leverage querying that data through the GraphQL API, it is trivial to store and retrieve an association to your place ID's when working with Itineraries

For enterprise clients, Alpaca can integrate with other authoritative place providers or establish a direct query environment to source information from your data. This may be a national database maintained by an administrative body, or other commercial organization.

Place Libraries

Place Libraries provide mechanisms to store GIS and place information on the Alpaca platform, and use this in order to present the content on itineraries or directories.

The Place Libraries can provide a storage environment that can be leveraged for broader use cases, such as storing all your place data to be presented and browsed on your website.

Mapping Libraries (Mapbox, Google, Leaflet, MapLibre etc)

The alpaca.tech itinerary technology is built with interoperability at its core, allowing you to integrate with any mapping library of your choice, such as Google, Mapbox, or Leaflet.

Our platform functions as a complementary tool to your chosen mapping client, equipping you with itinerary data in a format compatible with your library. For instance, with Mapbox, we host and serve optimised native vector tiles formats for direct styling and display.

We also offer additional resources, including regularly updated data sets like the ABS tourism region data and the Australian Tourism Data Warehouse, extending beyond the typical offerings of your chosen mapping library.

To be clear, we don't sell 'Mapbox' or any other mapping libraries. Alpaca enhances your selected mapping technology with powerful itinerary management and data tools.

End-user Wish-lists and Trip Planning

Alpaca supports the creation of pseudo-anonymous itineraries, which can be used for creating itineraries that are not associated with registered users on the Alpaca platform.

End-users should be registered with the developers application or website, using their preferred method of registration. No end-user personal information should be stored on the Alpaca platform.

In your application, the common approach is to create a pseudo-anonymous itinerary and if necessary to store a relationship to your users.

• Local Storage: If you prefer to keep things simple, the association for your application to the itinerary could be stored locally on the client using local storage.
• Itinerary ID Storage: Alternatively, you could expose a way to store any created itineraries within your application by users by tracking them against a user account in your platform.

1# Create a pseudo-anonymous itinerary that does not have an association to
2# a profile and do not require the use of a secret token for the profile.
3mutation {
4  createItinerary(
5    # Create an itinerary
6    itinerary: { title: "My Bookmarks" }
7  ) {
8    # Read back the ID of the created itinerary, and store where appropriate
9    itinerary {
10      id
11    }
12  }
13}

Pseudo-anonymous itineraries do not have auth permissions to modify them.

User Image Uploads

Media can also be uploaded to the alpaca.tech platform and incorporated into itineraries. This can open opportunities for more content creation from your end users, by allowing them to share their own media with content created.

More Integration Advice

You can contact the Alpaca team to discuss your project requirements and approach to leverage alpaca.tech within your architecture.