Data Assets API Documentation

API Endpoints #

The Destination Palestine Tourism Platform offers programmatic access to its rich dataset through a well-structured API. Connecting to these endpoints allows developers to retrieve information about various asset types, providing a seamless integration of platform data into external applications or services.

API Endpoint Structure #

The base URL for accessing API endpoints is https://assets.destinationpalestine.io/api/node/. To fetch data for a specific asset type, append the asset type to the base URL.

Endpoints: #

Asset Type	URL
Accommodation	https://assets.destinationpalestine.io/api/node/accommodation
Food & Beverage	https://assets.destinationpalestine.io/api/node/food_beverage
General Sites and Attractions	https://assets.destinationpalestine.io/api/node/sites_attractions
Religious Site	https://assets.destinationpalestine.io/api/node/religious_site
Tourism Service Provider	https://assets.destinationpalestine.io/api/node/tourism_service_provider

Retrieving Data #

To retrieve data from the API, perform HTTP GET requests to the respective endpoints. The response will be in JSON format, providing structured and comprehensive information about assets.

Connecting to the API endpoints provides a flexible and dynamic way to access the wealth of information available on the Destination Palestine Tourism Platform. Developers can integrate this data into their applications, creating a more interconnected and enriched user experience.

For more details and to explore the available fields, refer to the API documentation page.

API Basics #

The JSON:API is a powerful and standardized way to interact with the Destination Palestine Tourism Platform’s data. Whether you’re a developer building an application or exploring the data for analysis, this guide covers the fundamentals of making requests to retrieve information.

Requesting a List of Assets #

To request a list of assets from a certain content type, use the following endpoint structure:

Example Request (cURL):

# Retrieve a list of accommodations 
curl -X GET https://assets.destinationpalestine.io/api/node/accommodation 

Result:

The response will contain an array of assets, each represented as a JSON object.

Requesting a Single Node (Asset) #

To request a single node, specify the content type and the node ID in the endpoint:

Example Request (cURL):

# Retrieve a single accommodation (ID: 123) 
curl -X GET https://assets.destinationpalestine.io/api/node/sites_attractions/a8d6c723-ea06-4336-be84-4a542479134a

Result:

The response will contain the details of the specified asset.

Requesting Taxonomy Terms #

For taxonomy terms associated with assets, you can use a similar approach. Let’s take the example of sites & attractions types:

Example Request (cURL):

# Retrieve sites_attractions types 
curl -X GET https://assets.destinationpalestine.io/api/taxonomy_term/sites_attractions_type

Result:

The response will contain an array of taxonomy terms, each representing a category for the “accommodation” asset type.

Applying to Reference Fields #

For fields marked as “Reference Field” in assets, such as field_sites_attractions_type, the values are linked to taxonomy terms. When requesting an asset, you can retrieve the associated taxonomy term details.

Example Request for Asset with “Sites & Attractions Type”:

# Retrieve an accommodation (ID: 123) with associated accommodation type details 
curl -X GET https://assets.destinationpalestine.io/api/node/sites_attractions/a8d6c723-ea06-4336-be84-4a542479134a?include=field_sites_attractions_type

Result:

The response will include the details of the accommodation along with the associated accommodation type details.

Please be aware that relationships within the Destination Palestine Tourism Platform rely on UUID (Universally Unique Identifier) rather than the traditional numerical ID. When working with relationships, ensure you use the UUID associated with each entity for accurate and reliable connections.

API Filtering #

JSON:API filtering provides a powerful way to narrow down results based on specific criteria, ensuring that you retrieve only the information you need. Filters are applied as query parameters in the API request, allowing for a flexible and efficient way to tailor your data retrieval.

How Filtering Works #

To apply filtering, include the desired filters as query parameters in the API endpoint URL. Each filter corresponds to a field in the asset type you are querying. The platform’s JSON:API supports filtering based on various criteria, such as taxonomy terms, boolean values, numbers, and text fields.

Example: Retrieving “sites_attractions” with a Specific Field Value #

Suppose you want to retrieve all assets of the type “sites_attractions” where the field field_sites_attractions_type has a specific value. Here’s how you can structure the request:

Example Request (cURL):

# Retrieve sites_attractions with a specific field_sites_attractions_type value
curl -X GET 'https://assets.destinationpalestine.io/api/node/sites_attractions?filter[field_sites_attractions_type.id]=8b5ebcdc-f1c5-4c9d-8ebd-9f67d14adb86'

Result:

The response will contain a list of “sites_attractions” assets that match the specified filter criteria.

Explanation of the Request #

• filter[field_sites_attractions_type.id]: Specifies the field (field_sites_attractions_type) you want to filter.
• =8b5ebcdc-f1c5-4c9d-8ebd-9f67d14adb86: Specifies the value you are filtering for.
• For “Reference Field” field types, you will need to append .id after the field’s name.

This request will retrieve all assets of type “sites_attractions” where the value of field_sites_attractions_type matches the provided UUID.

JSON:API filtering is a valuable tool for customizing your data queries, allowing you to retrieve specific subsets of information that meet your criteria. Experiment with different filters to tailor your requests and obtain the data that best suits your needs.

For further information, refer to Drupal’s Official Documentation on this topic.

Assets to Media Server Integration #

MediaGraph is a powerful external service integrated into the Destination Palestine Tourism Platform, designed to streamline media management. Admins can leverage this service to host and organize images used across the platform, enhancing the visual representation of assets. Developers, in turn, can efficiently retrieve media-related information for assets through the provided integration fields.

Integration Fields #

field_related_media #

When admins create or update assets, they link media files from MediaGraph to each asset using the field_related_media field. This field contains essential information for developers to seamlessly retrieve and display media content associated with each asset.

Retrieving Media Information: #

• MediaGraph ID:
  • Access the unique identifier for the media item from field_related_media.field_mediagraph_uuid.
• Media URL:
  • Retrieve the URL for the media item on the MediaGraph server from field_related_media.field_mediagraph_image_orig.url.

field_mediagraph_tags #

In addition to direct media linkage, assets are enriched with descriptive tags stored in the field_mediagraph_tags field. These tags serve as valuable metadata, allowing developers to query the MediaGraph API for specific media items based on text phrases.

Utilizing Tags for Querying: #

• Querying MediaGraph API:
  • Developers can use the tags in field_mediagraph_tags to query the MediaGraph API for relevant media items.

Example Request (cURL):

# Retrieve MediaGraph ID and URL for an Asset
curl -X GET https://assets.destinationpalestine.io/api/node/accommodation/XX-XX-XX-XX

# Resulting JSON may contain:
# ...
# "field_related_media": {
#    "field_mediagraph_uuid": "media_uuid_here",
#    "field_mediagraph_image_orig": {
#        "url": "https://mediagraph.example.com/media/123/original/image.jpg"
#    }
# },
# "field_mediagraph_tags": ["tag1", "tag2", "tag3"]
# ...

The integration with MediaGraph enhances the platform’s media management capabilities, providing a centralized repository for images and facilitating seamless access for developers. By incorporating MediaGraph IDs, URLs, and descriptive tags, assets become more visually appealing and discoverable.

For more details on the integration fields and querying MediaGraph, refer to the platform’s API documentation.

Media from MediaGraph #

MediaGraph, also known as tv3.io, serves as the central hub for hosting and managing media assets on the Destination Palestine Tourism Platform. Developers can seamlessly retrieve the original files associated with assets by leveraging the information stored in the platform.

Retrieving Media from MediaGraph #

To retrieve media from MediaGraph, developers should use the information stored in the platform’s assets. Specifically, utilize the previously mentioned field:

• Field Name: field_related_media
  • Read the value field_related_media.field_mediagraph_uuid to obtain the unique identifier for the media item.

Example Request (cURL):

# Retrieve the original media file from MediaGraph
curl -X GET 'https://api.mediagraph.io/api/assets/{id}'

Result:

The response will contain a JSON response with a link to the original media file associated with the specified MediaGraph ID.

Additional Documentation #

For more details on interacting with MediaGraph and exploring its features, refer to the official MediaGraph documentation: MediaGraph Documentation

This documentation provides comprehensive information about MediaGraph’s capabilities, endpoints, and best practices.

Integrating with MediaGraph allows developers to seamlessly access and utilize original media files associated with assets on the Destination Palestine Tourism Platform. By following the provided guidance and referring to the MediaGraph documentation, developers can enhance their applications with rich media content.

Pagination #

API responses may be paginated for large datasets. Include the page query parameter to navigate through pages of results.

Example Request for Page 2

curl -X GET https://assets.destinationpalestine.io/api/node/accommodation?page=2

Example Response

{
  "data": [
    {
      "type": "accommodation",
      "id": "123",
      "attributes": {
        "official_name": "Example Hotel",
        "address": "123 Main Street",
        // Additional attributes...
      }
    },
    // Additional assets...
  ],
  "meta": {
    "count": 100,
    // Additional metadata...
  }
}

In the example response, the meta.count field indicates the total number of entries found. Developers can use this information to determine the extent of the dataset and navigate through the available pages accordingly.