# Static API

The Static API allows you to access unit data in JSON format. It opens new possibilities, especially for complex blocks and features where data is conditionally visible based on JS conditions.

We call it the "Static API" because it will generate static JSON files: once live, the data will change only when you republish your website.&#x20;

{% hint style="success" %}
As this is a static file, on a static website, there is no time to wait for the request to be done on a web server. The content is just a plain JSON file, therefore the time it takes to load its content is almost immediate.
{% endhint %}

### Use cases

Static API opens many possibilities:

* Doing search blocks, filtering is easier in Javascript. Without static API you have to get the data from the DOM
* Creating complex web components using data from unit
* [Showing / Hiding items based on the current date](https://galaxy-cms.gitbook.io/project/module/date-visibility)
* ... many more :rocket:

### Using Static API

Inside your theme directory, in the folder **`json`**, create a new JSON file

The **name of the file will be the key** used in the HTML to get the URL of the JSON file *(use a lowercase filename, separated with hyphens or dashes)*.

{% code title="json/my-hotels.json" %}

```javascript
{
	"module":"hotel",
	"fields": "name,url,has_photo,first_photo,short_description",
	"children": {
		"first_photo": "alt,url_square"
	}
}
```

{% endcode %}

**`module`** is the name of the module you would like to use (room, restaurant, hotel, etc...).&#x20;

**`fields`** list of the unit's field you need. Separate them by a comma and don't add any extra spaces.

**`children`** some fields return objects. For performance, this allows you to choose only the fields you need.

**`filters`** (see details below, allow to filter the data)

{% hint style="info" %}
You can have several JSON files for the same module (ex: `featured-hotels.json`, `all-hotels.json`, `booking-mask-hotels.json`)
{% endhint %}

In the HTML of your block, you can get the URL of the generated json file with this syntax `#$json|key$#`

Example, if you have a file `json/my-hotels.json`

```markup
<a href="#$json|my-hotels$#">Link to my_hotels.json</a>
```

The JSON body will be an array of objects:

```javascript
[
  {
    "name": "My hotel 1",
    "url": "https://my-link-to-hotel.com",
    "has_photo": 1,
    "first_photo": {
      "alt": "Alt of your image",
      "url_square": "url_of_the_image (for the ratio square)"
    }
  },
  {
    "name": "My hotel 2",
    "url": "https://my-link-to-hotel2.com",
    "has_photo": 1,
    "first_photo": {
      "alt": "Alt of your image",
      "url_square": "url_of_the_image (for the ratio square)"
    }
  }
]
```

{% hint style="success" %}
We advise to get data using [GalaxyHelpers.staticSearch()](https://galaxy-cms.gitbook.io/project/module/json-of-module-data/galaxyhelpers.staticsearch) function. It will fetch for you the JSON and return to you the result. Also, in some specific cases, it will perform additional filtering, for example for "offer date based visibility"
{% endhint %}

### Inline JSON

Sometimes, you need to access the JSON data, but you would prefer it to be directly in the HTML of the page.

{% hint style="info" %}
Adding this JSON data to the page will make the source HTML bigger. It's best to keep the smallest possible for page speed/performances.
{% endhint %}

Examples where you might want to use inline json

* you know this JSON will be very small and want to avoid an extra call
* the data needs to use the current context of the page (example multi-detail pages, offers on collection websites...)

This syntax writes the JSON directly in the HTML instead of having the link to the JSON file. \
Add the prefix <mark style="color:blue;">`|inline`</mark> to the usual syntax&#x20;

```html
#$json|ibe-config$# -> URL of the JSON
#$json|ibe-config|inline$# -> Inline version of the json
```

### Filtering data

You might want to get only a subset of data, for example only offers with "GP Only" checkbox activated, or only featured hotel. To do this, use the key **filters**

Example 1:

Get only the offers that have the "GP Only" checkbox activated (see key `filters`)

{% code title="json/test-offers.json" %}

```javascript
{
    "module":"offer",
    "fields": "url,first_photo,name,short_description,",
    "children": {
        "first_photo": "alt,url_panoramic,url_wide,url_standard,url_square,url_portrait,url_vertical"
    },
    "filters": {
        "is_guest_portal_only": 1
    }
}

```

{% endcode %}

The syntax is the same as the filters when writing loop in the HTML to get unit data.

### Fields: Get array of IDs instead of array of objects <a href="#array-id" id="array-id"></a>

Inside an item, for some keys, the value will be an array of objects; for example here, the key "`hotel_categories`":

```json
[
  {
    "id": 219,
    "name": "My hotel name",
    "hotel_categories": [
      {
        "id": 95,
        "name": "Wine",
        "slug": "wine"
      },
      {
        "id": 115,
        "name": "Pet Friendly",
        "slug": "pet-friendly"
      },
      {
        "id": 117,
        "name": "Family",
        "slug": "family"
      }
    ]
  }
  // other hotels here
]

```

If you wanted to filter only hotels that have the category **Family (id: 117)**, it would be faster to have in the javascript an array with only the IDs, something like that: (see <mark style="color:purple;background-color:blue;">`__ids_hotel_categories`</mark>)

```json
[
  {
    "id": 219,
    "name": "My hotel name",
    // only array of IDs for "hotel_categories"
    "__ids_hotel_categories": [95, 115, 117],
    "hotel_categories": [
      {
        "id": 95,
        "name": "Wine",
        "slug": "wine"
      },
      {
        "id": 115,
        "name": "Pet Friendly",
        "slug": "pet-friendly"
      },
      {
        "id": 117,
        "name": "Family",
        "slug": "family"
      }
    ]
  }
  // other hotels here
]

```

{% hint style="success" %}
To do this, use the prefix `__ids_` that will turn the data into an array of IDs.
{% endhint %}

For example, the `hotels` in `tc-group` unit, <mark style="color:blue;">`hotel_categories`</mark>  returns an array of objects with different categories. \
Adding <mark style="color:blue;">`__ids_hotel_categories`</mark> will add an array with only the IDs

{% code title="" %}

```javascript
{
  "module": "hotel",
  "fields": "name,hotel_categories,__ids_hotel_categories",
  "children": {
    "hotel_categories": "id,name,slug"
  }
}
```

{% endcode %}
