How to filter WordPress REST API for custom post type by taxonomy slug

I spent ages looking for an answer to my question of how to implement this, I knew that it was possible but I couldn’t seem to find the right answer anywhere. So I’m posting it here for my future reference and in case anyone else finds it.

The issue is compounded by there being so many links to old questions and tutorials for previous versions of the WordPress REST API. As of writing my version of wordpress is 4.9.8. And that makes it REST API v2.

I finally found the answer to my question here on stackexchange.

A little background

I have created a custom post type for my site of accommodation, and enabled the rest API for my custom type using the show_in_rest parameter when defining the custom post type.

I’ve also created a taxonomy called accommodation_size, and this classifies the accommodation.

Now, the part I was having trouble finding out is how to limit query results based on the taxonomy. I couldn’t find the info anywhere.

But I finally found the StackExchange post and it cleared everything up.

Example Request

To enable the filter to work, I had to add two extra args when creating the custom taxonomy.

'show_in_rest' => true, // This enables the REST API endpoint
'query_var' => true // This allows us to append the taxonomy param to the custom post api request.

Once this is done then you can call the custom post REST API, with our param.

The first thing to notice here is that the parameter name is the official name of the taxonomy, NOT the slug that you define in the rewrite block.

The second take home point is that you have to specify the Term ID as the parameter value. Using the slug for the term doesn’t work.

To get the id of the term you can use the taxonomy endpoint to query it, or do it in PHP if you are serverside.


$term = get_term_by('slug', 'large', 'accommodation_category');

This will return you a term id to use in your main request.

UPDATE: If you really need to use a slug as a parameter use a filter

If you have access to the theme or a can modify a plugin on the server, you can add a filter to your functions.php to create a new request parameter that enables requests via slug. You can add a custom filter, take a look to rest_{$this->post_type}_query hook. As discussed in this StackExchange answer.

 * Filter work post type by accommodation_category slug
 * @param array $args
 * @param WP_Rest_Rquest $request
 * @return array $args
function filter_rest_accommodation_query( $args, $request ) { 
    $params = $request->get_params(); 
        $args['tax_query'] = array(
                'taxonomy' => 'accommodation_category',
                'field' => 'slug',
                'terms' => explode(',', $params['accommodation_category_slug'])
    return $args; 
// add the filter 
add_filter( "rest_accommodation_query", 'filter_rest_accommodation_query', 10, 2 ); 

Once this is in place you can query via slug name like this:

I hope that might be of help to someone in the future. It might change in future versions of the API but it works for now and that’s all that matters!

6 thoughts on “How to filter WordPress REST API for custom post type by taxonomy slug

  1. Thank you so much for this clear explanation! I have a calendar of events for a community, and a group of sites that want to display subsets of the calendar. I thought I could do something fairly simple with the REST API, and as you say, “so many links to old questions and tutorials for previous versions of the WordPress REST API” got in the way. Much obliged!

  2. Thanks for the explanation.
    I have a question.
    How can I query the custom posts through custom taxonomy via slug and not taxonomy id ??

    1. Hi Pravin, If you can add a filter in php, you can modify the taxonomy query on the server to listen for a custom parameter, and create a new tax query that listens for the slug. I’ve update my post to add a way of doing that. Please see the update, querying by slug.

    1. the hook is a hook built in to wordpress. I link to it in my previous response. You have to create the filter with the name of your custom_post_type. So you would need to add a filter like this:
      add_filter( "rest_custom_post_type_query", "filter_rest_custom_post_type_query", 10, 2 ); where filter_rest_custom_post_type_query is the function that I defined above. I’ve linked to the wordpress docs above, but here’s the link again: rest_{$this->post_type}_query
      For your example above, you would then create a rest query that looked like this:

Leave a Reply

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