Dealing with Custom Taxonomies in the WP-API

Update: this article focuses on the WP-API v1. Click here for an article on filtering with the WP-API v2 in WordPress 4.7+.
I have recently started working on a mobile app for a WordPress site that relies heavily on custom taxonomies.
The app needs to pull in posts from WordPress through the WP-API, and allow user filtering based on taxonomy. This requires some special handling, since custom taxonomies don’t appear in the WP-API by default.

What’s a custom taxonomy?

Taxonomies are for categorization. An example of a taxonomy is a category or a post tag.
For example, this post is in the ‘category’ of ‘wp-api.’ We can have lots of terms like wp-api, tutorial, blog, or personal under the name ‘category.’ A custom taxonomy could be swapping the word ‘category’ for something like ‘device.’ So we could have terms like ‘iPhone’, ‘Android’, and ‘Windows’ under our ‘device’ taxonomy.
For more on custom taxonomies, check out these references.

Creating custom taxonomies

Creating custom taxonomies uses the register taxonomy function. It’s similar to creating a custom post type, and just like a CPT, it won’t show up the WP-API unless we add show_in_rest = true.
To create a custom taxonomy that shows up in the WP-API, we could do something like this:
[php]
_x( ‘Genres’, ‘taxonomy general name’ ),
// more labels here…
);
$args = array(
‘hierarchical’ => true,
‘labels’ => $labels,
‘show_ui’ => true,
‘show_in_rest’ => true,
‘show_admin_column’ => true,
‘query_var’ => true,
‘rewrite’ => array( ‘slug’ => ‘genre’ ),
);
register_taxonomy( ‘genre’, array( ‘book’ ), $args );
[/php]
The main thing to notice is the ‘show_in_rest’ argument, set to true.

Adding current taxonomies to the WP-API

If the taxonomy has already been created, or you don’t have access to the registration function, you can add the show_in_rest argument like this.
For a single taxonomy:
[php]
show_in_rest = true;
}
add_action( ‘init’, ‘sb_add_tax_to_api’, 30 );
[/php]
For multiple taxonomies, something like this:
[php]
show_in_rest = true;
}
}
add_action( ‘init’, ‘sb_add_taxes_to_api’, 30 );
[/php]

WP-API endpoint for custom taxonomies

After you’ve added your custom taxonomy to the WP-API using show_in_rest, you can navigate to the taxonomies or terms endpoint to see it in action.
For example, using the example of ‘genre’ from above, we could go to mysite.com/wp-json/wp/v2/terms/genre to see all of our genres. Let’s say we had a genre called ‘fiction’ with an ID of 212. To see information about only the fiction genre, we could visit mysite.com/wp-json/wp/v2/terms/genre/212
If we just wanted the structural information about the taxonomy, we could visit mysite.com/wp-json/wp/v2/taxonomies/genre
If we wanted to get only the posts in a certain term (like fiction), we could make a GET request to mysite.com/wp-json/wp/v2/posts?filter[genre]=fiction. You could do the same for a custom post type (assuming you’ve added show_in_rest = true for the post type) by using the CPT’s endpoint: mysite.com/wp-json/wp/v2/mycptslug?filter[genre]=fiction
I hope that helps! Let me know if you have any additional tips or questions in the comments.