SearchWP API Queries

REST API Add-on For SearchWP

Our SearchWP API plugin adds an endpoint to the WordPress REST API to allow you to run advanced searches via a RESTful API, thanks to the awesome powers of SearchWP. This endpoint uses the class SWP_Query, which is documented here.

This add-on does not required SearchWP. It did intentionally, but now it will fallback to using WP_Query id SearchWP is not installed. But SearchWP queries are indexed, so it should be faster when SearchWP is installed.

Supported Queries

Basic Queries

Search By Keyword

/wp-json/swp-api/?search=hobbits

Default is an empty string

Search Using A Supplemental Search Engine

/wp-json/swp-api/?search=hobbits&engine=hobbit_search

Default is “default”
Note: Engine must exists. Expect a 400 error if it does not.
See: Setting Up A Supplemental Search Engine

Control Posts Per Page

/wp-json/swp-api/?search=hobbits&posts_per_page=42

Default is current setting for posts_per_page
Note: Posts per page is limited to 50 by default. Use “cwp_swp_api_max_posts_per_page” filter to change.

Disable Pagination Of Results

/wp-json/swp-api/?search=hobbits&posts_per_page=5&nopaging=true

Default is false

Results Page

/wp-json/swp-api/?search=hobbits&posts_per_page=5&page=2

Default is 1

Limit Posts To Be Returned

/wp-json/swp-api/?search=hobbits&post__in=42,1

Default is false

Exclude Posts From Results

/wp-json/swp-api/?search=hobbits&post__not_in=42,1

Default is false

Meta Queries Based On Custom Posts

This plugin probably offers the most flexible meta queries via the REST API possible.

Basic Meta Query

Search by custom field value, key, with comparison.

/wp-json/swp-api/meta_query[key]=width&meta_query[value]=wide&meta_query[compare]=IN

Default is false
Note: All three parts of the meta_query are required. If any are omitted a 400 error will occur.

More Complex Meta Queries

Meta Relationships

Use variable meta_relation to change relationship been queries. Also, you can set compare, like with regular meta_queries. Make sure your compare argument is in the right order.

Example: Search where jedi field is “luke” or sith field is not “vader”.

wp-json/swp_api/search?meta_query[key][]=jedi&meta_query[value][]=luke&meta_query[compare][]=in&meta_query[key][]=sith&meta_query[value][]=vader&meta_query[compare][]=NOT%20IN&meta_relation=OR
Multiple Values In A Query Part

Put multiple fields into your query parts, by adding extra nesting levels in URL string. Order gets very tricky, numbers (remember to start at 0) help, as shown below.

Example: Search where jedi field is “luke” or “obi-wan” and sith field is not “vader”.

wp-json/swp_api/search?meta_query[key][]=jedi&meta_query[value][0][]=luke&meta_query[value][0][]=obi-wan&meta_query[compare][]=in&meta_query[key][]=sith&meta_query[value][]=vader&meta_query[compare][]=NOT%20IN&meta_relation=AND

Nested meta queries added in version 1.1.0 and allow for querying by multiple meta fields. Be sure to see the relevant section of the WP_Query docs

Taxonomy Based Queries

This plugin probably also offers the ability to do complex queries bases on taxonomies.

/wp-json/swp-api/tax_query[taxonomy]=category&tax_query[terms]=api&tax_query[field]=slug

Default is false
Note: All three parts of the tax_query are required. If any are omitted a 400 error will occur.
Note: At this time you may only query by a single term. There is an open issue for this, if you submit a patch for it, and that patch is merged, you will receive a prize.

Perform A Date Query

/wp-json/swp-api/date_query[year]=1982&date_query[month]=10&date_query[day]=13

Default is false
Note: All three parts of the date_query are required. If any are omitted a 400 error will occur.

Join Our Newsletter

Get helpful WordPress resources from our lead developer Josh Pollock, Caldera updates, and special savings.