Yoast SEO 14.0: REST API endpoint
With Yoast SEO 14.0 we’re introducing lots of new goodies. One of them is a Yoast SEO REST API endpoint that’ll give you all the metadata you need for a specific URL. This will make it very easy for headless WordPress sites to use Yoast SEO for all their SEO meta output.
There are two ways of using this: through its inclusion in the normal WP REST API responses and through our own endpoint.
Inclusion in WP REST API responses
When you’re retrieving a post like so:
https://example.com/wp-json/wp/v2/posts/1
Or like this:
http://example.com/wp-json/wp/v2/posts?slug=hello-world
You’ll receive a normale WP REST API response, with an additional field: yoast_head
. This additional field will contain a blob with all the necessary meta tags for that page. This works for the posts
, pages
, categories
, tags
and all custom post types and custom taxonomies.
For post type archives, when you query the types
endpoint the meta is included there, also on the yoast_head
field. If it is not there, the post type does not have a post type archive enabled.
Yoast SEO REST API syntax
The syntax is very simple, you just GET
to /wp-json/yoast/v1/get_head?url=
with the proper URL, for example:
https://example.com/wp-json/yoast/v1/get_head?url=https://example.com/hello-world/
This will return the following:
{ "head": "the complete, escaped, <head> output for Yoast SEO", "status": 200, }
The head
contains the complete meta output for the page. This means the Yoast SEO REST API output contains everything:
- The title
- The meta description, if you have one
- Robots meta tags
- The canonical URL
- Our Schema output
- OpenGraph meta data
- Twitter meta data
The API returns 404
for an existing page?
If the status
is not 200
but you’re certain the page exists, you’ll need to make sure your site is completely indexed. Just hitting save on the backend should save the post or page to the Indexables database. Note that Yoast SEO will return a head
for other statuses too, so you can use the output on, for instance, 404
pages.
If you have a notice in your site’s admin about indexing your site: please run that index process if you intend to rely on this API.
I don’t want this API on my site!
You can easily disable this API by going to SEO – General – Features and disabling the feature toggle.
Headless WordPress and Yoast SEO
With this Yoast SEO REST API endpoint we hope to support those people building headless WordPress sites a lot better. But we’d love to hear from you if you’re currently building headless WordPress sites. Is this useful to you? Would you like to see changes? Let us know in the comments!
Coming up next!
-
Event
Wordcamp Asia 2025
February 20 - 22, 2025 Team Yoast is at Attending, Sponsoring, Yoast Booth Wordcamp Asia 2025! Click through to see who will be there, what we will do, and more! See where you can find us next » -
SEO webinar
Webinar: How to start with SEO (December 18, 2024)
18 December 2024 Learn how to start your SEO journey the right way with our free webinar. Get practical tips and answers to all your questions in the live Q&A! All Yoast SEO webinars »
Hi,
I am having some issues with the rest api, if i’ve read correctly it should include the page title. I cannot see it in my response nor can I see it on the example link included above.
Am I missing a setting or is there a bug?
Thanks,
Sam
Hi,
We’re using WordPress in a headless manner. This WordPress runs on a separate subdomain (along the lines of cms.[example.com]), while the actual client-facing website runs on example.com.
By putting the entire in a blob, this code contains the canonical link and og:url with the subdomain in it. Is there any way to manipulate this from the WordPress side?
Kind regards
Robbert
I’ve got the exact same setup and issue. The domain in the canonical and og:url should be filterable in my opinion.
Hi Robbert and Toine,
You can filter the canonical through the
wpseo_canonical
filter and the opengraph url through thewpseo_opengraph_url
filter.For the canonical we’ve documented it here: https://developer.yoast.com/features/seo-tags/canonical-urls/api
For the opengraph output we haven’t finished the documentation yet, but it works similarly.
Hi Omar,
Thanks for the response. Even though this seems like a fair way to solve it, I think the developer experience could be better. Since one of the goals of this addition is to serve people better who are using WordPress in a headless manner, it would make sense along with the ‘Enable Rest API endpoint’ checkbox to be able to include a URL of where your headless website is located and update the canonical URL accordingly.
1. This way there’s no need for PHP coding for people using WordPress in a headless manner, I guess one of the motivations to go headless in the first place.
2. This way the entire response returned by the endpoint can be placed in the HTML by the frontend without any manipulation in between.
Just an idea, I’m sure there’s tons of nuances I’m missing here that prevent this from being a viable option, but who knows :-)
Thanks anyway for creating such a great product, thumbs up to the team!
Thanks, it’s a good start, but not what I was expecting to see when I read the title of the article.
Could all the fields be supplied as separate fields in the JSON document? You can still supply the blob of HTML too of course. This would be far more flexible in my opinion.
I’d also have preferred to see the data on the particular resource endpoints, as this plugin does:
https://github.com/maru3l/wp-api-yoast-meta
Hey Christopher, thanks for your feedback! We’ve added them to the endpoint as well.
We’re looking at adding the separate fields, but honestly, because the output needs to be completely correct, so I’m a bit hesitant in that.
If I would use ReactJS for my front-end, I would use this data and add it to my server-side code…. Right?
Yeah basically you can grab the field from the response and output it on the frontend.