Title: get_term_by
Published: April 25, 2014
Last modified: February 24, 2026

---

# get_term_by( string $field, string|int $value, string $taxonomy, string $output = OBJECT, string $filter ): 󠀁[WP_Term](https://developer.wordpress.org/reference/classes/wp_term/)󠁿|array|false

## In this article

 * [Description](https://developer.wordpress.org/reference/functions/get_term_by/?output_format=md#description)
    - [See also](https://developer.wordpress.org/reference/functions/get_term_by/?output_format=md#see-also)
 * [Parameters](https://developer.wordpress.org/reference/functions/get_term_by/?output_format=md#parameters)
 * [Return](https://developer.wordpress.org/reference/functions/get_term_by/?output_format=md#return)
 * [Source](https://developer.wordpress.org/reference/functions/get_term_by/?output_format=md#source)
 * [Related](https://developer.wordpress.org/reference/functions/get_term_by/?output_format=md#related)
 * [Changelog](https://developer.wordpress.org/reference/functions/get_term_by/?output_format=md#changelog)
 * [User Contributed Notes](https://developer.wordpress.org/reference/functions/get_term_by/?output_format=md#user-contributed-notes)

[ Back to top](https://developer.wordpress.org/reference/functions/get_term_by/?output_format=md#wp--skip-link--target)

Gets all term data from database by term field and data.

## 󠀁[Description](https://developer.wordpress.org/reference/functions/get_term_by/?output_format=md#description)󠁿

Warning: $value is not escaped for ‘name’ $field. You must do it yourself, if required.

The default $field is ‘id’, therefore it is possible to also use null for field,
but not recommended that you do so.

If $value does not exist, the return value will be false. If $taxonomy exists and
$field and $value combinations exist, the term will be returned.

This function will always return the first term that matches the `$field`– `$value`–`
$taxonomy` combination specified in the parameters. If your query is likely to match
more than one term (as is likely to be the case when `$field` is ‘name’, for example),
consider using [get_terms()](https://developer.wordpress.org/reference/functions/get_terms/)
instead; that way, you will get all matching terms, and can provide your own logic
for deciding which one was intended.

### 󠀁[See also](https://developer.wordpress.org/reference/functions/get_term_by/?output_format=md#see-also)󠁿

 * [sanitize_term_field()](https://developer.wordpress.org/reference/functions/sanitize_term_field/):
   The $context param lists the available values for [get_term_by()](https://developer.wordpress.org/reference/functions/get_term_by/)
   $filter param.

## 󠀁[Parameters](https://developer.wordpress.org/reference/functions/get_term_by/?output_format=md#parameters)󠁿

 `$field`stringrequired

Either `'slug'`, `'name'`, `'term_id'` (or `'id'`, `'ID'`), or `'term_taxonomy_id'`.

`$value`string|intrequired

Search for this term value.

`$taxonomy`stringrequired

Taxonomy name. Optional, if `$field` is `'term_taxonomy_id'`.

`$output`stringoptional

The required return type. One of OBJECT, ARRAY_A, or ARRAY_N, which correspond to
a [WP_Term](https://developer.wordpress.org/reference/classes/wp_term/) object, 
an associative array, or a numeric array, respectively.

Default:`OBJECT`

`$filter`stringoptional

How to sanitize term fields. Default `'raw'`.

## 󠀁[Return](https://developer.wordpress.org/reference/functions/get_term_by/?output_format=md#return)󠁿

 [WP_Term](https://developer.wordpress.org/reference/classes/wp_term/)|array|false
[WP_Term](https://developer.wordpress.org/reference/classes/wp_term/) instance (
or array) on success, depending on the `$output` value.
 False if `$taxonomy` does
not exist or `$term` was not found.

## 󠀁[Source](https://developer.wordpress.org/reference/functions/get_term_by/?output_format=md#source)󠁿

    ```php
    function get_term_by( $field, $value, $taxonomy = '', $output = OBJECT, $filter = 'raw' ) {

    	// 'term_taxonomy_id' lookups don't require taxonomy checks.
    	if ( 'term_taxonomy_id' !== $field && ! taxonomy_exists( $taxonomy ) ) {
    		return false;
    	}

    	// No need to perform a query for empty 'slug' or 'name'.
    	if ( 'slug' === $field || 'name' === $field ) {
    		$value = (string) $value;

    		if ( 0 === strlen( $value ) ) {
    			return false;
    		}
    	}

    	if ( 'id' === $field || 'ID' === $field || 'term_id' === $field ) {
    		$term = get_term( (int) $value, $taxonomy, $output, $filter );
    		if ( is_wp_error( $term ) || null === $term ) {
    			$term = false;
    		}
    		return $term;
    	}

    	$args = array(
    		'get'                    => 'all',
    		'number'                 => 1,
    		'taxonomy'               => $taxonomy,
    		'update_term_meta_cache' => false,
    		'orderby'                => 'none',
    		'suppress_filter'        => true,
    	);

    	switch ( $field ) {
    		case 'slug':
    			$args['slug'] = $value;
    			break;
    		case 'name':
    			$args['name'] = $value;
    			break;
    		case 'term_taxonomy_id':
    			$args['term_taxonomy_id'] = $value;
    			unset( $args['taxonomy'] );
    			break;
    		default:
    			return false;
    	}

    	$terms = get_terms( $args );
    	if ( is_wp_error( $terms ) || empty( $terms ) ) {
    		return false;
    	}

    	$term = array_shift( $terms );

    	// In the case of 'term_taxonomy_id', override the provided `$taxonomy` with whatever we find in the DB.
    	if ( 'term_taxonomy_id' === $field ) {
    		$taxonomy = $term->taxonomy;
    	}

    	return get_term( $term, $taxonomy, $output, $filter );
    }
    ```

[View all references](https://developer.wordpress.org/reference/files/wp-includes/taxonomy.php/)
[View on Trac](https://core.trac.wordpress.org/browser/tags/6.9.4/src/wp-includes/taxonomy.php#L1099)
[View on GitHub](https://github.com/WordPress/wordpress-develop/blob/6.9.4/src/wp-includes/taxonomy.php#L1099-L1160)

## 󠀁[Related](https://developer.wordpress.org/reference/functions/get_term_by/?output_format=md#related)󠁿

| Uses | Description | 
| [get_terms()](https://developer.wordpress.org/reference/functions/get_terms/)`wp-includes/taxonomy.php` |

Retrieves the terms in a given taxonomy or list of taxonomies.

  | 
| [taxonomy_exists()](https://developer.wordpress.org/reference/functions/taxonomy_exists/)`wp-includes/taxonomy.php` |

Determines whether the taxonomy name exists.

  | 
| [get_term()](https://developer.wordpress.org/reference/functions/get_term/)`wp-includes/taxonomy.php` |

Gets all term data from database by term ID.

  | 
| [is_wp_error()](https://developer.wordpress.org/reference/functions/is_wp_error/)`wp-includes/load.php` |

Checks whether the given variable is a WordPress Error.

  |

[Show 2 more](https://developer.wordpress.org/reference/functions/get_term_by/?output_format=md#)
[Show less](https://developer.wordpress.org/reference/functions/get_term_by/?output_format=md#)

| Used by | Description | 
| [WP_REST_Menus_Controller::create_item()](https://developer.wordpress.org/reference/classes/wp_rest_menus_controller/create_item/)`wp-includes/rest-api/endpoints/class-wp-rest-menus-controller.php` |

Creates a single term in a taxonomy.

  | 
| [get_linksbyname()](https://developer.wordpress.org/reference/functions/get_linksbyname/)`wp-includes/deprecated.php` |

Gets the links associated with category $cat_name.

  | 
| [get_linkobjectsbyname()](https://developer.wordpress.org/reference/functions/get_linkobjectsbyname/)`wp-includes/deprecated.php` |

Gets an array of link objects associated with category $cat_name.

  | 
| [WP_Query::get_queried_object()](https://developer.wordpress.org/reference/classes/wp_query/get_queried_object/)`wp-includes/class-wp-query.php` |

Retrieves the currently queried object.

  | 
| [WP_Query::get_posts()](https://developer.wordpress.org/reference/classes/wp_query/get_posts/)`wp-includes/class-wp-query.php` |

Retrieves an array of posts based on query variables.

  | 
| [get_category_by_slug()](https://developer.wordpress.org/reference/functions/get_category_by_slug/)`wp-includes/category.php` |

Retrieves a category object by category slug.

  | 
| [get_cat_ID()](https://developer.wordpress.org/reference/functions/get_cat_id/)`wp-includes/category.php` |

Retrieves the ID of a category from its name.

  | 
| [get_term_link()](https://developer.wordpress.org/reference/functions/get_term_link/)`wp-includes/taxonomy.php` |

Generates a permalink for a taxonomy term archive.

  | 
| [wp_unique_term_slug()](https://developer.wordpress.org/reference/functions/wp_unique_term_slug/)`wp-includes/taxonomy.php` |

Makes term slug unique, if it isn’t already.

  | 
| [wp_update_term()](https://developer.wordpress.org/reference/functions/wp_update_term/)`wp-includes/taxonomy.php` |

Updates term based on arguments provided.

  | 
| [wp_insert_term()](https://developer.wordpress.org/reference/functions/wp_insert_term/)`wp-includes/taxonomy.php` |

Adds a new term to the database.

  | 
| [_wp_preview_terms_filter()](https://developer.wordpress.org/reference/functions/_wp_preview_terms_filter/)`wp-includes/revision.php` |

Filters terms lookup to set the post format.

  | 
| [get_bookmarks()](https://developer.wordpress.org/reference/functions/get_bookmarks/)`wp-includes/bookmark.php` |

Retrieves the list of bookmarks.

  | 
| [get_post_format_link()](https://developer.wordpress.org/reference/functions/get_post_format_link/)`wp-includes/post-formats.php` |

Returns a link to a post format index.

  | 
| [wp_update_nav_menu_object()](https://developer.wordpress.org/reference/functions/wp_update_nav_menu_object/)`wp-includes/nav-menu.php` |

Saves the properties of a menu or create a new menu with those properties.

  | 
| [wp_get_nav_menu_object()](https://developer.wordpress.org/reference/functions/wp_get_nav_menu_object/)`wp-includes/nav-menu.php` |

Returns a navigation menu object.

  | 
| [wp_xmlrpc_server::_insert_post()](https://developer.wordpress.org/reference/classes/wp_xmlrpc_server/_insert_post/)`wp-includes/class-wp-xmlrpc-server.php` |

Helper method for wp_newPost() and wp_editPost(), containing shared logic.

  |

[Show 12 more](https://developer.wordpress.org/reference/functions/get_term_by/?output_format=md#)
[Show less](https://developer.wordpress.org/reference/functions/get_term_by/?output_format=md#)

## 󠀁[Changelog](https://developer.wordpress.org/reference/functions/get_term_by/?output_format=md#changelog)󠁿

| Version | Description | 
| [5.5.0](https://developer.wordpress.org/reference/since/5.5.0/) | Added `'ID'` as an alias of `'id'` for the `$field` parameter. | 
| [4.4.0](https://developer.wordpress.org/reference/since/4.4.0/) | `$taxonomy` is optional if `$field` is `'term_taxonomy_id'`. Converted to return a [WP_Term](https://developer.wordpress.org/reference/classes/wp_term/) object if `$output` is `OBJECT`. | 
| [2.3.0](https://developer.wordpress.org/reference/since/2.3.0/) | Introduced. |

## 󠀁[User Contributed Notes](https://developer.wordpress.org/reference/functions/get_term_by/?output_format=md#user-contributed-notes)󠁿

 1.   [Skip to note 5 content](https://developer.wordpress.org/reference/functions/get_term_by/?output_format=md#comment-content-422)
 2.    [Codex](https://profiles.wordpress.org/codex/)  [  11 years ago  ](https://developer.wordpress.org/reference/functions/get_term_by/#comment-422)
 3.  [You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fget_term_by%2F%23comment-422)
     Vote results for this note: 5[You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fget_term_by%2F%23comment-422)
 4.  **Examples**
      Examples to get terms by name and taxonomy type (taxonomy_name as
     category, post_tag or custom taxonomy).
 5.      ```php
         // Get term by name ''news'' in Categories taxonomy.
         $category = get_term_by('name', 'news', 'category')
     
         // Get term by name ''news'' in Tags taxonomy.
         $tag = get_term_by('name', 'news', 'post_tag')
     
         // Get term by name ''news'' in Custom taxonomy.
         $term = get_term_by('name', 'news', 'my_custom_taxonomy')
     
         // Get term by name ''Default Menu'' from theme's nav menus.
         // (Alternative to using wp_get_nav_menu_items)
         $menu = get_term_by('name', 'Default Menu', 'nav_menu');
         ```
     
 6.  By id (term_id, not post_id):
 7.      ```php
         // Get term by id (''term_id'') in Categories taxonomy.
         get_term_by('id', 12, 'category')
         ```
     
 8.   [Log in to add feedback](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fget_term_by%2F%3Freplytocom%3D422%23feedback-editor-422)
 9.   [Skip to note 6 content](https://developer.wordpress.org/reference/functions/get_term_by/?output_format=md#comment-content-3730)
 10.   [nicoseijas](https://profiles.wordpress.org/nicoseijas/)  [  6 years ago  ](https://developer.wordpress.org/reference/functions/get_term_by/#comment-3730)
 11. [You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fget_term_by%2F%23comment-3730)
     Vote results for this note: 3[You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fget_term_by%2F%23comment-3730)
 12. Example of retrieving a category by it’s name:
 13.     ```php
         $category = get_term_by('name', 'Term Name', 'category');
         ```
     
 14. **Output:**
 15.     ```php
         (object) array(
            'term_id' => 49,
            'name' => 'Term Name',
            'slug' => 'term-name',
            'term_group' => 0,
            'term_taxonomy_id' => 49,
            'taxonomy' => 'category',
            'description' => '',
            'parent' => 0,
            'count' => 286,
            'filter' => 'raw',
         )
         ```
     
 16.  [Log in to add feedback](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fget_term_by%2F%3Freplytocom%3D3730%23feedback-editor-3730)
 17.  [Skip to note 7 content](https://developer.wordpress.org/reference/functions/get_term_by/?output_format=md#comment-content-1645)
 18.   [bcworkz](https://profiles.wordpress.org/bcworkz/)  [  10 years ago  ](https://developer.wordpress.org/reference/functions/get_term_by/#comment-1645)
 19. [You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fget_term_by%2F%23comment-1645)
     Vote results for this note: 1[You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fget_term_by%2F%23comment-1645)
 20. [get_term_by()](https://developer.wordpress.org/reference/functions/get_term_by/)
     returns a single [WP_Term](https://developer.wordpress.org/reference/classes/wp_term/)
     object. Because of core changes from v4.1 – 4.3, it’s now possible for multiple
     terms to match the supplied name or slug parameters. The [WP_Term](https://developer.wordpress.org/reference/classes/wp_term/)
     Object returned will be the first matching term found by mySQL, there is no indication
     that other matching terms may exist. If there is any possibility of multiple terms
     having the same name or slug in your application, you should use [get_terms()](https://developer.wordpress.org/reference/functions/get_terms)
     instead of [get_term_by()](https://developer.wordpress.org/reference/functions/get_term_by/).
 21.  [Log in to add feedback](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fget_term_by%2F%3Freplytocom%3D1645%23feedback-editor-1645)
 22.  [Skip to note 8 content](https://developer.wordpress.org/reference/functions/get_term_by/?output_format=md#comment-content-4708)
 23.   [Shabti Kaplan](https://profiles.wordpress.org/shabti/)  [  5 years ago  ](https://developer.wordpress.org/reference/functions/get_term_by/#comment-4708)
 24. [You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fget_term_by%2F%23comment-4708)
     Vote results for this note: 1[You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fget_term_by%2F%23comment-4708)
 25. If you are using a custom taxonomy, this might not work unless you add the third
     parameter, namely the taxonomy name:
 26. My custom taxonomy is `wpdocs_playlist`.
 27.     ```php
         $playlist = get_term_by( 'slug', $playlist_key, 'wpdocs_playlist' );
         ```
     
 28.  [Log in to add feedback](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fget_term_by%2F%3Freplytocom%3D4708%23feedback-editor-4708)

You must [log in](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fget_term_by%2F)
before being able to contribute a note or feedback.