How do I Filter Custom Post Type by Custom Taxonomy in the newest Wordpress RESTful API?

Question

I've a Custom Post Type called clock and a taxonomy called clock_category on my website. It is working well and All the clocks can be accessed from the REST endpoint https://myapp.dev/wp-json/wp/v2/clock

But I don't know how to filter them by the Clock category, say I want to get all the clocks which are made of wood

I tried different URLs but none of them seems to be working https://myapp.dev/wp-json/wp/v2/clock?clock_category=wood https://myapp.dev/wp-json/wp/v2/clock?clock_category=10

and many more. All I got was the full result set.

Here is the code

<?php
add_action( 'init', 'clock' );

function clock() {
    $labels = array(
        "name" => __( 'Clock', 'mywp' ),
        "singular_name" => __( 'clock', 'mywp' ),
        "menu_name" => __( 'Clock', 'mywp' ),
        "all_items" => __( 'All Clock', 'mywp' ),
        "add_new" => __( 'Add New Clock', 'mywp' ),
        "add_new_item" => __( 'Add New Clock', 'mywp' ),
        "edit_item" => __( 'Edit Clock', 'mywp' ),
        "new_item" => __( 'New Clock', 'mywp' ),
        "view_item" => __( 'View Clock', 'mywp' ),
        "search_items" => __( 'Search Clock', 'mywp' ),
        "not_found" => __( 'No Clock Found', 'mywp' ),
        "not_found_in_trash" => __( 'No Clock found in trash', 'mywp' ),
        "parent_item_colon" => __( 'Parent Clock', 'mywp' ),
        "featured_image" => __( 'Feature Image for Clock', 'mywp' ),
        "set_featured_image" => __( 'Set featured Clock image', 'mywp' ),
        "remove_featured_image" => __( 'Remove featured image for Clock', 'mywp' ),
        "use_featured_image" => __( 'Use featured image for Clock', 'mywp' ),
        "archives" => __( 'Clock archives', 'mywp' ),
        "insert_into_item" => __( 'Insert into Clock', 'mywp' ),
        "uploaded_to_this_item" => __( 'Uploaded to this Clock', 'mywp' ),
        "items_list_navigation" => __( 'Clock list navigation', 'mywp' ),
        "items_list" => __( 'Clock List', 'mywp' ),
        "parent_item_colon" => __( 'Parent Clock', 'mywp' ),
        );

$args = array(
    "label" => __( 'Clock', 'mywp' ),
    "labels" => $labels,
    "description" => "Clock",
    "public" => true,
    "publicly_queryable" => true,
    "show_ui" => true,
    "show_in_rest" => true,
    "rest_base" => "clock",
    "has_archive" => false,
    "show_in_menu" => true,
            "exclude_from_search" => false,
    "capability_type" => "post",
    "map_meta_cap" => true,
    "hierarchical" => false,
    "rewrite" => array( "slug" => "clock", "with_front" => true ),
    "query_var" => true,

    "supports" => array( "title", "editor", "thumbnail", "custom-fields", "page-attributes", "post-formats" ),      
    "taxonomies" => array( ),
        );
register_post_type( "clock", $args );

}

add_action( 'init', 'create_clock_tax' );

function create_clock_tax() {
    register_taxonomy(
        'clock_category',
        'clock',
        array(
            'label' => __( 'Clock Category' ),
            'rewrite' => array( 'slug' => 'clock_category' ),
            'hierarchical' => true,
        )
    );
}

Hope someone help me out on this. I've been trying to solve this for 5 hours and nothing seems to be working.

Answer 1

We can check out the /wp/v2/clock endpoint's arguments here:

https://myapp.dev/wp-json/wp/v2/

If we add the 'show_in_rest' => true, argument, when registering the custom clock_category taxonomy, it will add a support for this GET/POST argument:

clock_category: {
    required: false,
    default: [ ],
    description: "Limit result set to all items that have the 
        specified term assigned in the clock_category taxonomy.",
    type: "array",
    items: {
        type: "integer"
    }
},

and this GET argument:

clock_category_exclude: {
    required: false,
    default: [ ],
    description: "Limit result set to all items except those that have the 
        specified term assigned in the clock_category taxonomy.",
    type: "array",
    items: {
        type: "integer"
    }
}

It will also add the /wp/v2/clock_category endpoint.

So to filter the clock posts by a single clock category ID:

https://myapp.dev/wp-json/wp/v2/clock?clock_category=10

or by multiple clock category IDs:

https://myapp.dev/wp-json/wp/v2/clock?clock_category=10,11,12

To exclude from a single category ID:

https://myapp.dev/wp-json/wp/v2/clock?clock_category_exclude=13

or exclude from multiple clock category IDs:

https://myapp.dev/wp-json/wp/v2/clock?clock_category_exclude=13,14

Answer 2

I know that this is a super old question, but I just ran into the same issue, and perhaps this answer will help someone.

If you want to filter a custom post type by a custom taxonomy through REST, you need to enable it in both the register_post_type and register_taxonomy arguments.

I found the answer in the Core Handbook: Registering A Custom Taxonomy With REST API Support

I was missing these parameters from my register_taxonomy function:

    'query_var'             => true,
    'rewrite'               => array( 'slug' => 'genre' ),
    'show_in_rest'          => true,
    'rest_base'             => 'genre',
    'rest_controller_class' => 'WP_REST_Terms_Controller',

It looks like the person who asked this question, is also missing those arguments in their register_taxonomy function, so it should work once he/she adds that.

The rest_controller_class and rest_base are optional. Once I enabled it in my code, then the endpoint for my custom post type worked. Example url below:

https://localsite.com/wp-json/wp/v2/custom_post_type_name?taxonomy_name=935

Note that the "taxonomy name" is the name of taxonomy when you register it, not the slug for the taxonomies themselves.