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:
_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:
show_in_rest = true;
add_action( ‘init’, ‘sb_add_tax_to_api’, 30 );
For multiple taxonomies, something like this:
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 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
If we just wanted the structural information about the taxonomy, we could visit
If we wanted to get only the posts in a certain term (like fiction), we could make a GET request to[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:[genre]=fiction
I hope that helps! Let me know if you have any additional tips or questions in the comments.






4 responses to “Dealing with Custom Taxonomies in the WP-API”

  1. Fred Avatar

    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 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. Fred Avatar

    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 in case the details are useful.)

    1. Scott Avatar

      Hi Fred, I haven’t messed around with custom taxonomies in v2, but using the REST Filter plugin seems like the way to go for now.

  3. Jahangeer Shams Avatar
    Jahangeer Shams

    Very helpful well-written article.