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
// hook into the init action and call create_book_taxonomies when it fires
add_action( 'init', 'create_book_taxonomies', 0 );

// create two taxonomies, genres and writers for the post type "book"
function create_book_taxonomies() {
	// Add new taxonomy, make it hierarchical (like categories)
	$labels = array(
		'name'              => _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 );

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
function sb_add_tax_to_api() {
    $mytax = get_taxonomy( 'genre' );
    $mytax->show_in_rest = true;
}
add_action( 'init', 'sb_add_tax_to_api', 30 );

For multiple taxonomies, something like this:

<?php
function sb_add_taxes_to_api() {
    $taxonomies = get_taxonomies( '', 'objects' );
    
    foreach( $taxonomies as $taxonomy ) {
	    $taxonomy->show_in_rest = true;
    }
}
add_action( 'init', 'sb_add_taxes_to_api', 30 );

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.

3 thoughts on “Dealing with Custom Taxonomies in the WP-API

  1. Thanks for a useful post which has set me more or less on the right track. Unfortunately I’m using the current latest version in WordPress 4.7 beta 4, and it seems the API no longer offers these endpoints. I’ve just been told the latest version of v2 has dropped the filter parameter (see https://core.trac.wordpress.org/ticket/38378). And when I do a request to /wp-json/wp/v2/terms/my_custom_taxonomy and even just /wp-json/wp/v2/terms/, the API returns the error “No route was found matching the URL and request method”.

  2. Thanks Scott, I found this a very useful post. Unfortunately the latest version of the REST API has dropped support for the filter argument. Can you suggest any other way I can get only posts belonging to a certain custom post type which have a particular slug value for a custom taxonomy?

    (I’ve posted this question on http://wordpress.stackexchange.com/questions/248182/wp-rest-api-no-longer-supports-filter-param-so-how-do-i-get-posts-in-a-custom-t in case the details are useful.)

Leave a Reply

Your email address will not be published. Required fields are marked *