Get Featured Image in REST API

In this tutorial, I’d like to continue showing you some tips and tricks that can be useful when working with WordPress REST API, so I am going to show you two ways how you can get a featured image:

1. If you know a featured image ID, you can always use the /wp/v2/media/{$media_id} endpoint, I am going to discuss this method first.
2. Another story: if all you have is a post ID, and you need to get a featured image URL from it.

Method 1. Get a Featured Image by Its ID

Of course, when you know the ID of a target featured image, everything becomes as easy as pie.

Basically, all we need to do is to run a GET request to /wp/v2/media/{$media_id}.

Let me show an example of how we can do it in PHP using the WordPress HTTP API function for GET requests – wp_remove_get().

$response = wp_remote_get( "YOUR-SITE/wp-json/wp/v2/media/{$media_id}" );
if( 'OK' === wp_remote_retrieve_response_message( $response ) ) {
	$body = json_decode( wp_remote_retrieve_body( $response ), true );
	print_r( $body );
}

When you run a request like this, you’re going to have a bunch of featured image information available.

Let me highlight the most interesting data:

For example, let’s try to get and print a featured image URL of the medium size:

echo $body->media_details->sizes->medium->source_url;

Method 2. Get a Featured Image by Post ID

First of all, it is worth mentioning that when you have a post ID, you can easily get its featured image ID like this:

$response = wp_remote_get( "YOUR-SITE/wp-json/wp/v2/posts/{$post_id}" );
if( 'OK' === wp_remote_retrieve_response_message( $response ) ) {
	$body = json_decode( wp_remote_retrieve_body( $response ), true );
	echo $body[ 'featured_media' ];
}

And then, if you need to get a featured image URL as well, you need to perform additional REST API requests to /wp/v2/media/$image_id.

Of course, the idea of sending two REST API requests when we can send just one can lead to disastrous results. For example, my customers, who use my Simple WP Crossposting plugin, asked me for a feature that would allow them to update featured image alt text and other information for quite a long time, but I didn’t want to add it until I found a way to do that without creating an extra REST API request, because I didn’t want to sacrifice the plugin performance.

And this is what we’re going to do now – we will try to find a way to get a feature image URL using just a single REST API request.

The good news is that it is quite easy to do, we can just register one more field in the REST API response with a simple filter hook and register_rest_field() function.

/*
 * @snippet: WordPress API get featured image in a single REST API request
 * @author: Misha Rudrastyh
 * @url: https://rudrastyh.com/wordpress/rest-api-get-featured-image-url.html
 */
add_action( 'rest_api_init', function() {

	register_rest_field( 
		'post', // an object type (like "post", "term", "comment")
		'featured_image_data', // we are going to store image information here
		array(
			'get_callback' => 'rudr_get_featured_image_data',
		)
	);

} );

function rudr_get_featured_image_data( $post, $field_name, $request ) {
	
	if( empty( $post[ 'featured_media' ] ) ) {
		return;
	}
	
	$image_id = (int) $post[ 'featured_media' ];
	
	if( ! $image = get_post( $image_id ) ) {
		return;
	}
	
	return array(
		'src' => wp_get_attachment_url( $image_id ),
		'alt' => get_post_meta( $image_id, '_wp_attachment_image_alt', true ),
		'caption' => $image->post_excerpt,
	);
}

The code above should be inserted into the target site from where we’re trying to get a featured image.

By the way, it is not necessary to use get_post() together with wp_get_attachment_url() in order to get a featured image URL like this. For example, you can also do it with the wp_get_attachment_image_src() function.

function rudr_get_featured_image_data( $post, $field_name, $request ) {
	
	if( empty( $post[ 'featured_media' ] ) ) {
		return;
	}
	
	$image_id = (int) $post[ 'featured_media' ];
	
	$image = wp_get_attachment_image_src( $image_id, 'large' );
	
	if( empty( $image[0] ) ) {
		return;
	}
	
	return array(
		'src' => $image[0],
	);
}

You can also provide an image size name here on line 25.

Everything is ready, now you can create REST API requests to the target site and get featured image URLs of its posts. Let’s just slightly change the above example:

echo "<img src='{$body[ 'featured_image_data' ][ 'src' ]}' alt='{$body[ 'featured_image_data' ][ 'alt' ]}' />";

Method 3. Using _embed parameter

This method seems more like a hack to me, but, if you add ?_embed parameter at the end of the following REST API endpoints:

• /wp/v2/posts/{$post_id}?_embed,
• /wp/v2/posts/?_embed,

then you can easily get all the featured image information from either $body[ '_embedded' ][ 'wp:featuredmedia' ][0] or $body[0][ '_embedded' ][ 'wp:featuredmedia' ][0].

For example, let’s jump to the example we used before and add the ?_embed parameter there:

$response = wp_remote_get( "YOUR-SITE/wp-json/wp/v2/posts/{$post_id}?_embed" );
if( 'OK' === wp_remote_retrieve_response_message( $response ) ) {
	$body = json_decode( wp_remote_retrieve_body( $response ), true );
	// get featured image URL and print it
	echo $body[ '_embedded' ][ 'wp:featuredmedia' ][0][ 'source_url' ];
}

Get Global Featured Image in Shared Media Library

In case you’re using my Shared Media Library plugin for WordPress Multisite, then, when sending REST API requests in order to get specific posts from sub-sites, you can easily get the global featured image using the featured_media_global response parameter.

Example:

$response = wp_remote_get( "YOUR-SITE/wp-json/wp/v2/posts/{$post_id}" );
if( 'OK' === wp_remote_retrieve_response_message( $response ) ) {
	$body = json_decode( wp_remote_retrieve_body( $response ), true );
	print_r( $body[ 'featured_media_global' ] );
}

The JSON response will look like this:

# WordPress, Attachments, REST API

Misha Rudrastyh

Hey guys and welcome to my website. For more than 15 years I've been doing my best to share with you some superb WordPress guides and tips for free.

Need some developer help? Contact me

Follow me on X