WP Loupe Search API (Developer Guide)

WP Loupe exposes a REST API that lets you build your own search UI (theme template, JS widget, Gutenberg block, React app, etc.) on top of the same index WP Loupe uses internally.

Endpoints

GET /wp-json/wp-loupe/v1/search?q=... (legacy, kept for backward compatibility)
POST /wp-json/wp-loupe/v1/search (recommended: JSON filters, facets, geo, rich sorting)

Concepts

Index readiness

Search requires a ready index per post type.

When postTypes: "all" is used, WP Loupe only searches post types that have a ready index.
If no configured post type has a ready index, the API returns HTTP 400.

Allowlisted fields

Filtering, sorting, facets, and geo operations are restricted to fields that are explicitly enabled in Settings → WP Loupe.

Filter fields must be enabled as Filterable
Sort fields must be enabled as Sortable
Facet fields must be enabled as Filterable (terms facet)
Geo requires a dedicated geo-point field:
- Geo radius filtering requires the field to be Filterable
- Geo distance sorting (geo.sort) requires the field to be Sortable

If you request an operation on a non-allowlisted field, the API returns HTTP 400.

Preparing fields (hooks + data shape)

WP Loupe’s REST API only lets clients filter/sort/facet/geo on fields that are enabled in the schema.

Most sites will configure this in Settings → WP Loupe → Field Settings. If you’re building an integration or need to enforce fields programmatically, use the schema hooks below.

1) Facets (terms)

Terms facets require the field to be:

indexed (indexable: true)
allowlisted as filterable (filterable: true)
stored as a string or an array of strings

Example: add a facet field backed by post meta.

// 1) Allowlist the field in the schema.
add_filter( 'wp_loupe_schema_post', function ( array $schema ): array {
  $schema['audience'] = [
    'weight'         => 1.0,
    'indexable'      => true,
    'filterable'     => true,  // enables filtering + terms facets
    'sortable'       => false,
    'sort_direction' => 'desc',
  ];
  return $schema;
} );

// 2) Store the value in post meta as string or array of strings.
//    (Arrays become multi-valued facets.)
add_action( 'save_post', function ( int $post_id ) {
  // Example: multi-valued facet.
  update_post_meta( $post_id, 'audience', [ 'beginner', 'developer' ] );
} );

2) Geo (radius filtering + distance sorting)

Geo requires a dedicated geo-point field stored as an array:

// Stored as post meta:
// [ 'lat' => 59.9139, 'lng' => 10.7522 ]
// (or use 'lon' instead of 'lng')

To enable geo features:

Geo radius filtering requires the field to be Filterable.
Geo distance sorting (geo.sort) requires the field to be Sortable.

Example:

// 1) Allowlist the geo field.
add_filter( 'wp_loupe_schema_post', function ( array $schema ): array {
  $schema['location'] = [
    'weight'         => 1.0,
    'indexable'      => true,
    'filterable'     => true, // required for geo radius filtering
    'sortable'       => true, // required for geo.sort distance ordering
    'sort_direction' => 'asc',
  ];
  return $schema;
} );

// 2) Store the geo-point in post meta.
add_action( 'save_post', function ( int $post_id ) {
  update_post_meta( $post_id, 'location', [
    'lat' => 59.9139,
    'lng' => 10.7522,
  ] );
} );

If your geo field is stored as post meta and you need to override “meta sortability” decisions, you can use:

add_filter( 'wp_loupe_is_safely_sortable_meta_post', function ( bool $is_sortable, string $field_name ): bool {
  if ( 'location' === $field_name ) {
    return true;
  }
  return $is_sortable;
}, 10, 2 );

3) Sorting (non-geo)

Sorting requires the field to be:

indexed (indexable: true)
allowlisted as sortable (sortable: true)
stored as a scalar (string/number) for post meta fields

Example:

add_filter( 'wp_loupe_schema_post', function ( array $schema ): array {
  $schema['rating'] = [
    'weight'         => 1.0,
    'indexable'      => true,
    'filterable'     => false,
    'sortable'       => true,
    'sort_direction' => 'desc',
  ];
  return $schema;
} );

add_action( 'save_post', function ( int $post_id ) {
  update_post_meta( $post_id, 'rating', 4.7 );
} );

Note: if you already have data in meta, you typically only need the schema hook + a reindex (Settings → WP Loupe → Reindex, or wp wp-loupe reindex).

POST /search

Request body

{
  "q": "search text",
  "postTypes": "all",
  "page": { "number": 1, "size": 10 },
  "filter": {
    "type": "and",
    "items": [
      { "type": "pred", "field": "category", "op": "eq", "value": "news" },
      { "type": "pred", "field": "post_author", "op": "eq", "value": 123 }
    ]
  },
  "sort": [
    { "by": "_score", "order": "desc" },
    { "by": "post_date", "order": "desc" }
  ],
  "facets": [
    { "type": "terms", "field": "category", "size": 10, "minCount": 1 }
  ],
  "geo": {
    "field": "location",
    "near": { "lat": 59.9139, "lon": 10.7522 },
    "radiusMeters": 5000,
    "sort": { "order": "asc" },
    "includeDistance": true
  }
}

Top-level properties

q (string, required): the search query.
postTypes ("all" | string[], optional, default "all"): which post types to search.
- "all" resolves to the subset of configured post types that have a ready index.
page.number (int, optional, default 1): 1-based page.
page.size (int, optional, default 10): page size (1–100).
filter (object, optional): JSON filter AST (see below).
sort (array, optional): sorting instructions.
facets (array, optional): terms facets.
geo (object, optional): geo radius + geo sorting.

Notes:

Fields used in filter, sort, facets, and geo must be allowlisted in Settings (see Allowlisted fields above).
For geo, geo.near.lon is supported; geo.near.lng is also accepted for convenience.

Response

{
  "hits": [
    {
      "id": 123,
      "post_type": "post",
      "post_type_label": "Post",
      "title": "Example title",
      "excerpt": "…",
      "url": "https://example.test/example",
      "_score": 12.345,
      "_distanceMeters": 3210
    }
  ],
  "facets": {
    "category": {
      "type": "terms",
      "buckets": [
        { "value": "news", "count": 12 },
        { "value": "events", "count": 4 }
      ]
    }
  },
  "pagination": {
    "total": 42,
    "per_page": 10,
    "current_page": 1,
    "total_pages": 5
  },
  "tookMs": 8
}

Notes:

_score is always included.
_distanceMeters is included only when geo.includeDistance is true.

Filter AST (JSON)

WP Loupe accepts a structured JSON filter. The server translates it into the underlying Loupe filter syntax.

Groups

{ "type": "and", "items": [ <expr>, <expr>, ... ] }
{ "type": "or", "items": [ <expr>, <expr>, ... ] }
{ "type": "not", "item": <expr> }

Predicates

Predicates use a single shape:

{ "type": "pred", "field": "fieldName", "op": "eq", "value": "example" }

Supported op values:

eq, ne
in, nin (value must be a non-empty array)
lt, lte, gt, gte
between (value must be [min, max] or { "min": ..., "max": ... })
exists (value must be boolean)

Literal values

The API accepts:

strings
numbers
booleans
null
dates as either:
- date-only YYYY-MM-DD
- ISO-8601 timestamp (e.g. 2025-12-18T10:11:12Z)

Facets

Only terms facets are supported.

{
  "facets": [
    { "type": "terms", "field": "category", "size": 10, "minCount": 1 }
  ]
}

Geo search

{
  "geo": {
    "field": "location",
    "near": { "lat": 59.9139, "lon": 10.7522 },
    "radiusMeters": 5000,
    "sort": { "order": "asc" },
    "includeDistance": true
  }
}

field must be a geo-point field.
near is required.
radiusMeters is optional; when present, the server filters to that radius.
sort.order can be "asc" or "desc".

Errors

Errors are returned as WordPress REST errors with HTTP 400.

Example (missing q):

{
  "code": "wp_loupe_missing_query",
  "message": "Missing or empty query parameter \"q\".",
  "data": { "status": 400 }
}

Gutenberg block example (client-side search)

This is a minimal example showing how a custom block could call the POST endpoint.

1) Install dependencies

If you build blocks with @wordpress/scripts, you’ll typically already have these:

@wordpress/api-fetch
@wordpress/element
@wordpress/components

2) Example `edit` implementation

import apiFetch from '@wordpress/api-fetch';
import { useEffect, useMemo, useState } from '@wordpress/element';
import { TextControl, Spinner } from '@wordpress/components';

export default function Edit() {
	const [query, setQuery] = useState('');
	const [isLoading, setIsLoading] = useState(false);
	const [hits, setHits] = useState([]);

	const body = useMemo(() => ({
		q: query,
		postTypes: 'all',
		page: { number: 1, size: 10 },
    sort: [ { by: '_score', order: 'desc' } ],
	}), [query]);

	useEffect(() => {
		let cancelled = false;
		if (!query.trim()) {
			setHits([]);
			return () => { cancelled = true; };
		}

		setIsLoading(true);
		apiFetch({
			path: '/wp-loupe/v1/search',
			method: 'POST',
			data: body,
		}).then((res) => {
			if (cancelled) return;
			setHits(res?.hits || []);
		}).catch(() => {
			if (cancelled) return;
			setHits([]);
		}).finally(() => {
			if (cancelled) return;
			setIsLoading(false);
		});

		return () => { cancelled = true; };
	}, [body, query]);

	return (
		<div className="wp-loupe-search-block">
			<TextControl
				label="Search"
				value={ query }
				onChange={ setQuery }
				placeholder="Type to search…"
			/>
			{ isLoading ? <Spinner /> : null }
			<ul>
        { hits.map((h) => (
					<li key={ h.id }>
            <a href={ h.url }>{ h.title }</a>
					</li>
				)) }
			</ul>
		</div>
	);
}

PHP example (server-side call)

$response = wp_remote_post(
	rest_url( 'wp-loupe/v1/search' ),
	[
		'headers' => [ 'Content-Type' => 'application/json' ],
		'body'    => wp_json_encode(
			[
				'q'        => 'wordpress',
				'postTypes' => 'all',
				'page'     => [ 'number' => 1, 'size' => 10 ],
			]
		),
	]
);

$body = json_decode( wp_remote_retrieve_body( $response ), true );

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

WP Loupe Search API (Developer Guide)

Concepts

Index readiness

Allowlisted fields

Preparing fields (hooks + data shape)

1) Facets (terms)

2) Geo (radius filtering + distance sorting)

3) Sorting (non-geo)

POST /search

Request body

Top-level properties

Response

Filter AST (JSON)

Groups

Predicates

Literal values

Facets

Geo search

Errors

Gutenberg block example (client-side search)

1) Install dependencies

2) Example `edit` implementation

PHP example (server-side call)

Uh oh!

FilesExpand file tree

search-api.md

Latest commit

History

search-api.md

File metadata and controls

WP Loupe Search API (Developer Guide)

Concepts

Index readiness

Allowlisted fields

Preparing fields (hooks + data shape)

1) Facets (terms)

2) Geo (radius filtering + distance sorting)

3) Sorting (non-geo)

POST /search

Request body

Top-level properties

Response

Filter AST (JSON)

Groups

Predicates

Literal values

Facets

Geo search

Errors

Gutenberg block example (client-side search)

1) Install dependencies

2) Example edit implementation

PHP example (server-side call)

2) Example `edit` implementation