Getting articles tagged with a specific taxonomy term

You can specify a taxonomy auxiliary element in a content type. All content items of that type can be linked to specific taxonomy terms.

In this scenario, you will learn how to use the Delivery API to retrieve only the content items with a specific taxonomy term.

1. Get taxonomy term codename

First, you need to get the taxonomy term's codename.

  1. In Kentico Cloud, navigate to the Taxonomy section.
  2. Select a taxonomy group.
  3. View a codename of a taxonomy term by clicking {#}.

After you copy the codename of a taxonomy term, you can build your request to the API.

2. Get only articles with a specific taxonomy term

The Taxonomy auxiliary element contains a list of the codenames of taxonomy terms that are linked to the given item.

For example, you can use the elements.<taxonomy_element_codename>[contains] query parameter and a taxonomy term's codename to get only the content items linked with the given taxonomy term.

Here's an example of retrieving all articles for a barista persona.

curl --request GET \
  --url '[contains]=barista'
  --header 'content-type: application/json'
using KenticoCloud.Delivery;

// Initializes a content delivery client
IDeliveryClient client = DeliveryClientBuilder

// Gets articles tagged with the barista persona
// Create strongly typed models according to
DeliveryItemListingResponse<Article> response = await client.GetItemsAsync<Article>(
    new EqualsFilter("system.type", "article")
    new ContainsFilter("elements.personas", "barista")

var items = response.Items;
const KenticoCloud = require('kentico-cloud-delivery');

// Create strongly typed models according to
class Article extends KenticoCloud.ContentItem {
    constructor() {

const deliveryClient = new KenticoCloud.DeliveryClient({
    projectId: '975bf280-fd91-488c-994c-2f04416e5ee3',
    typeResolvers: [
        new KenticoCloud.TypeResolver('article', () => new Article())

    .containsFilter('elements.personas', ['barista'])
    .subscribe(response => console.log(response)); 
import { ContentItem, DeliveryClient, Fields, TypeResolver } from 'kentico-cloud-delivery';

// Create strongly typed models according to
export class Article extends ContentItem {
    public title: Fields.TextField;
    public summary: Fields.TextField;
    public post_date: Fields.DateTimeField;
    public teaser_image: Fields.AssetsField;
    public related_articles: Article[];

const deliveryClient = new DeliveryClient({
    projectId: '975bf280-fd91-488c-994c-2f04416e5ee3',
    typeResolvers: [
        new TypeResolver('article', () => new Article)

    .containsFilter('elements.personas', ['barista'])
    .subscribe(response => console.log(response));

DeliveryClient client = new DeliveryClient("975bf280-fd91-488c-994c-2f04416e5ee3");

List<NameValuePair> params = DeliveryParameterBuilder.params()
    .filterEquals("system.type", "article")
    .filterContains("elements.personas", "barista")

// Create strongly typed models according to
List<ArticleItem> items = client.getItems(ArticleItem.class, params);
import com.kenticocloud.delivery_core.*;
import com.kenticocloud.delivery_rx.*;

import io.reactivex.Observer;
import io.reactivex.disposables.Disposable;
import io.reactivex.functions.Function;

// Prepares an array to hold strongly-typed models
List<TypeResolver<?>> typeResolvers = new ArrayList<>();

// Registers the type resolver for articles
typeResolvers.add(new TypeResolver<>(Article.TYPE, new Function<Void, Article>() {
    public Article apply(Void input) {
        return new Article();

// Prepares the DeliveryService configuration object
String projectId = "975bf280-fd91-488c-994c-2f04416e5ee3";
IDeliveryConfig config = DeliveryConfig.newConfig(projectId)

// Initializes a DeliveryService for Java projects
IDeliveryService deliveryService = new DeliveryService(config);

// Gets articles tagged with specific taxonomy term using a simple request
List<Article> items = deliveryService.<Article>items()
    .equalsFilter("system.type", "article")
    .containsFilter("elements.personas", Arrays.asList("barista"))

// Gets articles tagged with specific taxonomy term using RxJava2
    .equalsFilter("system.type", "article")
    .containsFilter("elements.personas", Arrays.asList("barista"))
    .subscribe(new Observer<DeliveryItemListingResponse<Article>>() {
        public void onSubscribe(Disposable d) {

        public void onNext(DeliveryItemListingResponse<Article> response) {
            // Gets the articles
            List<Article> items = response.getItems();

        public void onError(Throwable e) {

        public void onComplete() {

// Defined by Composer to include required libraries
require __DIR__ . '/vendor/autoload.php';

use KenticoCloud\Delivery\DeliveryClient;
use KenticoCloud\Delivery\QueryParams;

$client = new DeliveryClient('975bf280-fd91-488c-994c-2f04416e5ee3');

$items = $client->getItems((new QueryParams())
            ->equals('system.type', 'article')
            ->contains('personas', 'barista'));
import KenticoCloud

let client = DeliveryClient.init(projectId: "975bf280-fd91-488c-994c-2f04416e5ee3")

let customQuery = "items?system.type=article&elements.personas=barista"

// More about strongly-typed models
client.getItems(modelType: Article.self, customQuery: customQuery) { (isSuccess, itemsResponse, error) in
    if isSuccess {
        if let articles = itemsResponse?.items {
            // Use your items here
    } else {
        if let error = error {