Search Post by Post Meta in Rest API

WordPress provides the Rest API support for posts, pages, and custom post types which have set the show_in_rest parameter as true.

We have also the Rest API support for the tags, categories, and custom taxonomies which have the same show_in_rest parameter as true.

Table of content

#Overview Overview

We have Rest API endpoints for the post & pages as below:

• /wp-json/wp/v2/posts/
• /wp-json/wp/v2/pages/

And Rest API endpoints for tags & categories as below:

• /wp-json/wp/v2/tags/
• /wp-json/wp/v2/categories/

When we visit the Rest API endpoint then we see the result in JSON format. For example when we visit the /wp-json/wp/v2/posts/ then we see something like the below screenshot:

Now we see the id, date, guid, slug, title, etc of each post. By default, WordPress adds a list of fields for each post.

Below is the complete list of fields that we can assess in Rest API.

id
date
date_gmt
guid.rendered
modified
modified_gmt
slug
status
type
link
title.rendered
content.rendered
excerpt.rendered
author
featured_media
comment_status
ping_status
sticky
template
format
meta
categories
tags
_links

We can use the parameter _fields to get the specific fields in the response.

E.g.

When we use request /wp-json/wp/v2/posts/?_fields=id then we see only the ID field of each post in response.

Top ↑

#What is the Problem? What is the Problem?

We can filter the posts by passing the parameters like:

• /wp-json/wp/v2/posts/?categories=23 – Return all the posts which have category ID 23.
• /wp-json/wp/v2/posts/?tags=334 – Return all the posts which have tag ID 334.
• /wp-json/wp/v2/posts/?categories=3,4&tags=334 – Return all the posts which have categories 3 & 4 and tag ID 334.

Most of the times we need to filter the posts by post meta. And we need to filter the post, page or custom post type with custom fields or post meta.

Let’s create a scenario to demonstrate how to filter the posts with custom fields or with post meta.

I’m going to add the location meta key and store meta values for 2 posts.

E.g.

• I am setting the meta value Pune for the post-ID 40182.
• And meta value Mumbai for the post-ID 40159.

I’m using the WP CLI command wp post meta add <post-id> to set the post meta.

Below are the commands:

wp post meta add 40182 location Pune
wp post meta add 40159 location Mumbai

Here, I’m adding meta key location with value Pune for post-ID 40182

And meta key location with value Mumbai for post-ID 40159.

After execution above commands, you can see Success: Added custom field.

See the below screenshot for reference:

Now, We want to filter the posts by meta key location.

When we visit the below URL then it should return the appropriate result.

• /wp-json/wp/v2/posts/?meta_key=location&meta_value=Pune – Expect to return post 40182.
• /wp-json/wp/v2/posts/?meta_key=location&meta_value=Mumbai– Expect to return post 40159.

Top ↑

#What is the Solution? What is the Solution?

In WordPress, we have a filter rest_{$this->post_type}_query which allows us to add the query parameter support for the Rest API.

In this filter the value ${$this->post_type} indicate the post type name. So, We can use the filter:

• rest_post_query – To filter post type rest API query.
• rest_page_query – To filter the page type rest API query.
• rest_docs_query – To filter docs (custom post type) rest API query.

Let’s use filter rest_post_query to add custom field support for the posts. Use below code snippet to add the custom field support for the posts.

Here, We have used a filter and passed the parameters meta_key & meta_value in the query. So, We can use them as below:

/wp-json/wp/v2/posts/?meta_key=<key>&meta_value=<value>

Lets get the posts which have meta key location and value Pune

/wp-json/wp/v2/posts/?meta_key=location&meta_value=pune&_fields=id

Here we can see only 1 post is returned whose id is 40182.

Note: I have used _fields=id to get only post IDs to capture the screenshot.

Let’s do the same to retrieve the post which have location Mumbai.

/wp-json/wp/v2/posts/?meta_key=location&meta_value=mumbai&_fields=id