Search Post by Post Meta in Rest API


WordPress provides the Rest API support for post, 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 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 to the /wp-json/wp/v2/posts/ then we see someting like below screenshot:

Search Post by Post Meta in Rest API 1
Rest API Posts List

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

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


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


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

Search Post by Post Meta in Rest API 2
Rest API Only ID field in Response

Top ↑

Problem 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.


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

Im using 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 below screenshot for reference:

Search Post by Post Meta in Rest API 3
WP CLI Add Custom Field

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

When we visit below URL then it should return 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 ↑

Solution Solution

In WordPress we have a filter rest_{$this->post_type}_query which allow 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 page type rest API query.
  • rest_docs_query – To filter docs (custom post type) rest API query.

Lets 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 filter and pass the parameters meta_key & meta_value in the query. So, We can use them as below:


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


Search Post by Post Meta in Rest API 4
Post with Meta Value Pune.

Here we can see only 1 post is return 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.


Search Post by Post Meta in Rest API 5
Post with Meta Value Mumbai.

One thought on “Search Post by Post Meta in Rest API

  1. I blog frequently and I really thank you for your information. Thiis great article has truly peajed my interest.
    I’m going tto take a note of your blog annd keep checking for
    new information about once a week. I subscribed to your RSS
    feed as well.

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.

%d bloggers like this: