Querying WordPress Taxonomy Terms

Get the Name and URL for All Terms Associated with a WordPress Taxonomy

Use the get_terms() function to get the terms associated with a taxonomy where 'my-taxonomy-name' is the taxonomy key registered in register_taxonomy().

$terms = get_terms( 'my-taxonomy-name' );
if ( ! empty( $terms ) && ! is_wp_error( $terms ) ) {
    foreach ( $terms as $term ) {
        $term_link = get_term_link( $term );
        echo esc_url( $term_link );
        echo wp_kses_post( $term->name );
    }
}

To get a count of the posts each term is applied to

$terms = get_terms( 'my-taxonomy-name' );
if ( ! empty( $terms ) && ! is_wp_error( $terms ) ) {
    foreach ( $terms as $term ) {
        // print the name and the count
        echo wp_kses_post( $term->name );
        echo $term->count;
    }
}

Retrieve Only the Parent Terms When the Taxonomy is Hierarchical

Add the argument 'parent' => 0 to the array of options when running get_terms():

$terms = get_terms(  'my-taxonomy-name' , array( 'parent' => 0 ) );
if ( ! empty( $terms ) && ! is_wp_error( $terms ) ) {
    foreach ( $terms as $term ) {
        echo wp_kses_post( $term->name ) . "\n";
    }
}

Using WP_Term_Query Instead of get_terms() for Greater Control

See the WordPress Developer Documentation on the WP_Term_Query __construct() method for a comprehensive list of arguments that can be applied to the query.

Query the 15 most used terms in descending order of use:

$term_query = new \WP_Term_Query( array(
    'taxonomy'   => 'my-taxonomy-name', 
    'orderby'    => 'count',
    'order'      => 'DESC',
    'fields'     => 'all',
    'hide_empty' => true,
    'number'     => 15,
) );

if ( ! empty( $term_query->terms ) ) {
    foreach ( $term_query->terms as $term ) {
        $term_link = get_term_link( $term );
        echo esc_url( $term_link );
        echo wp_kses_post( $term->name );
    }
}

Get a Specific Term or Terms

Use the 'include => array(<term_id>, <term_id>) argument in the array of options when running get_terms() to fetch specific terms. Where 123 is the ID of a term we want to do something with:

$terms = get_terms(array(
    'taxonomy' => 'my-taxonomy-name',
    'hide_empty' => false,
    'include' => array( 123 ),  
));

foreach ( $terms as $term ) {
    // do something with the term
}

Get All Children of a Hierarchical WordPress Taxonomy

Use the get_term_children() function to get the children of a term where the $term_id, is the ID of the parent term (which might be retrieved on an individual page via get_the_ID() for example) and the $my-taxonomy-name is the taxonomy key registered in register_taxonomy().

<?php
$term_id = 123;
$my_taxonomy_name = 'spam';

$termchildren = get_term_children( $term_id, $my_taxonomy_name );

foreach ( $termchildren as $child ) {
    $term = get_term_by( 'id', $child, $my_taxonomy_name );
    echo wp_kses_post( $term->name );
}

Get the Parent Terms When the Taxonomy is Hierarchical

Once you have a Term object, access the parent ID via the parent attribute an use that with the get_term() function to retrieve the parent term object:

$terms = get_the_terms( $post_id, 'my-taxonomy-name' );
if ( ! empty( $terms ) && ! is_wp_error( $terms ) ) {
    // simplified for demonstration; if multiple terms are applied, $parent is set to the last one if accessed after the loop
    foreach ( $terms as $term ) {
        $parent = $term;  // assume $term is a parent to begin with
        if ( ! $term->parent == '0' ) {
            // $term is a child, redeclare the $parent variable
            $parent = get_term( $term->parent, $term->taxonomy );
        }

        // do something with the parent term
    }
}

Get the Terms for a Post

Use the wp_get_post_terms() function or the get_the_terms() function to get the terms for an individual post. wp_get_post_terms() will hit the database each time it retrieves data while get_the_terms() will draw from the cache. In either case, the function will return an array:

$my_taxonomy_name = 'spam';   
wp_get_post_terms( get_the_ID(), $my_taxonomy_name ); ?>

That can then be used, for example, to output the applied terms:

$terms = wp_get_post_terms( get_the_ID(), $my_taxonomy_name );
if ( count( $terms ) > 0 ) {
    foreach( $terms as $term ) {
        echo esc_html( $term->name );
    }
}

Identify the Primary Term for a Post with YoastSEO

If using YoastSEO, you can set a primary term and retrieve it with the meta key _yoast_wpseo_primary_<taxonomy>, where <taxonomy> is the snake case taxonomy name, e.g. category if using the default Category taxonomy.

get_post_meta( $post_id, '_yoast_wpseo_primary_<taxonomy>', true ); // returns the ID of the primary term

Additional Resources

Smashing Magazine has a great article on setting up and using custom taxonomies which covers the get_terms() function and using the WP_Query() class.

Feedback?

Email us at enquiries@kinsa.cc.