Filter Queries with Field-level Translation

It is possible to use filter queries with stories translated using Storyblok’s field-level translation. The field key must be extended with __i18n__ and a language code configured in the space settings. The following syntax applies:

stories/?filter_query[field__i18n__language_code][operation]=value

The following criteria must be fulfilled to successfully use filter queries with translated stories:

• The space must be configured to publish languages independently.
• The space must be configured to have use_filter_query_in_translated_stories enabled.
• The request must contain the language parameter specifying the target language.
• The request must contain version=published.

Note

For spaces created before February 6th, 2024, please contact Storyblok’s support team to enable the internal use_filter_query_in_translated_stories option. For spaces created after February 6th, 2024, this option is enabled by default.

Examples Use Cases

• filter_query[headline__i18n__de][like]=Die Symphonie der Erde*

  Returns all stories whose headline starts with the words “Die Symphonie der Erde” and are published in German, represented by the language code de.

• filter_query[headline__i18n__es_co][like]=Sinfonía de la Tierra: Navegar por las maravillas y los desafíos de nuestro oasis azul

  Returns all stories with this exact headline that are published in Spanish (Colombia), represented by the language code es-co.

Caution

Please note that the language code needs to be formatted with an underscore in the filter_query (es_co), even if it is defined with a hyphen in the space settings (es-co).

Example Request and Response

cURL

curl "https://api.storyblok.com/v2/cdn/stories?filter_query%5Bheadline__i18n__es_co%5D%5Bin%5D=Sinfon%C3%ADa+de+la+Tierra%3A+Navegar+por+las+maravillas+y+los+desaf%C3%ADos+de+nuestro+oasis+azul&version=published&language=es-co"

JS client

// Using the Universal JavaScript Client:
// https://github.com/storyblok/storyblok-js-client
Storyblok.get('cdn/stories', {
  "filter_query[headline__i18n__es_co][in]": "Sinfonía de la Tierra: Navegar por las maravillas y los desafíos de nuestro oasis azul",
  "version": "published",
  "language": "es-co"
})
  .then(response => {
    console.log(response)
  }).catch(error => {
    console.log(error)
  })

PHP client

$client = new \Storyblok\Client('YOUR_STORYBLOK_SPACE_ACCESS_TOKEN');

$client->getStories([
  "filter_query[headline__i18n__es_co][in]" => "Sinfonía de la Tierra => Navegar por las maravillas y los desafíos de nuestro oasis azul",
  "version" => "published",
  "language" => "es-co"
])->getBody();

Java

HttpResponse<String> response = Unirest.get("https://api.storyblok.com/v2/cdn/stories?filter_query%5Bheadline__i18n__es_co%5D%5Bin%5D=Sinfon%C3%ADa+de+la+Tierra%3A+Navegar+por+las+maravillas+y+los+desaf%C3%ADos+de+nuestro+oasis+azul&version=published&language=es-co")
  .asString();

C#

var client = new RestClient("https://api.storyblok.com/v2/cdn/stories?filter_query%5Bheadline__i18n__es_co%5D%5Bin%5D=Sinfon%C3%ADa+de+la+Tierra%3A+Navegar+por+las+maravillas+y+los+desaf%C3%ADos+de+nuestro+oasis+azul&version=published&language=es-co");
var request = new RestRequest(Method.GET);

IRestResponse response = client.Execute(request);

Python

import requests

url = "https://api.storyblok.com/v2/cdn/stories"

querystring = {"filter_query[headline__i18n__es_co][in]":"Sinfonía de la Tierra: Navegar por las maravillas y los desafíos de nuestro oasis azul","version":"published","language":"es-co"}

payload = ""
headers = {}

response = requests.request("GET", url, data=payload, headers=headers, params=querystring)

print(response.text)

Ruby

require 'storyblok'
client = Storyblok::Client.new(token: 'YOUR_TOKEN')

client.stories({:params => {
  "filter_query[headline__i18n__es_co][in]" => "Sinfonía de la Tierra => Navegar por las maravillas y los desafíos de nuestro oasis azul",
  "version" => "published",
  "language" => "es-co"
}})

Swift

import Foundation

let request = NSMutableURLRequest(url: NSURL(string: "https://api.storyblok.com/v2/cdn/stories?filter_query%5Bheadline__i18n__es_co%5D%5Bin%5D=Sinfon%C3%ADa+de+la+Tierra%3A+Navegar+por+las+maravillas+y+los+desaf%C3%ADos+de+nuestro+oasis+azul&version=published&language=es-co")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0)
request.method = "GET"

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()

Response

{
  "stories": [
    {
      "name": "Earth's Symphony: Navigating the Wonders and Challenges of Our Blue Oasis",
      "created_at": "2024-02-16T14:22:09.108Z",
      "published_at": "2024-03-12T13:15:31.325Z",
      "id": 444996765,
      "uuid": "660452d2-1a68-4493-b5b6-2f03b6fa722b",
      "content": {
        "_uid": "6bdf037c-f713-415c-a26a-8a9cfc926c85",
        "image": {
          "id": 14114772,
          "alt": "",
          "name": "",
          "focus": "",
          "title": "",
          "source": "",
          "filename": "https://a.storyblok.com/f/276232/2560x1946/ee938cf736/earth.jpg",
          "copyright": "",
          "fieldtype": "asset",
          "meta_data": {},
          "is_private": "",
          "is_external_url": false
        },
        "author": "51eed33d-855f-415c-ac0d-4404e03b89e1",
        "topics": ["solar-system"],
        "content": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.",
        "headline": "Sinfonía de la Tierra: Navegar por las maravillas y los desafíos de nuestro oasis azul",
        "component": "article",
        "scheduled": "2023-10-01 15:00",
        "categories": ["45d968b6-5790-4fbb-aa41-5781b8edde51", "d8e48716-0ecf-4059-b568-343bf54e4128"],
        "highlighted": false
      },
      "slug": "earths-symphony-navigating-wonders-challenges-blue-oasis",
      "full_slug": "es-co/articles/earths-symphony-navigating-wonders-challenges-blue-oasis",
      "sort_by_date": null,
      "position": 0,
      "tag_list": [],
      "is_startpage": false,
      "parent_id": 444991588,
      "meta_data": null,
      "group_id": "8d99d18d-5c97-42cd-a646-51e0c553f26a",
      "first_published_at": "2024-02-16T14:30:11.990Z",
      "release_id": null,
      "lang": "es-co",
      "path": null,
      "alternates": [],
      "default_full_slug": null,
      "translated_slugs": null
    }
  ],
  "cv": 1710249331,
  "rels": [],
  "links": []
}