get_term_by( string $field, string|int $value, string $taxonomy = '', string $output = OBJECT, string $filter = 'raw' )

Get all Term data from database by Term field and data.


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() instead; that way, you will get all matching terms, and can provide your own logic for deciding which one was intended.

See also



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


(string|int) (Required) Search for this term value.


(string) (Optional) Taxonomy name. Optional, if $field is 'term_taxonomy_id'.

Default value: ''


(string) (Optional) The required return type. One of OBJECT, ARRAY_A, or ARRAY_N, which correspond to a WP_Term object, an associative array, or a numeric array, respectively.

Default value: OBJECT


(string) (Optional) How to sanitize term fields.

Default value: 'raw'


(WP_Term|array|false) WP_Term instance (or array) on success, depending on the $output value. False if $taxonomy does not exist or $term was not found.


File: wp-includes/taxonomy.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;
		case 'name':
			$args['name'] = $value;
		case 'term_taxonomy_id':
			$args['term_taxonomy_id'] = $value;
			unset( $args['taxonomy'] );
			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 );


Version Description
5.5.0 Added 'ID' as an alias of 'id' for the $field parameter.
4.4.0 $taxonomy is optional if $field is 'term_taxonomy_id'. Converted to return a WP_Term object if $output is OBJECT.
2.3.0 Introduced.

© 2003–2019 WordPress Foundation
Licensed under the GNU GPLv2+ License.