Comprehensive Guide to Using Directorist REST APIs for Directory

Introduction

Directorist is a powerful WordPress directory plugin that provides a robust REST API for managing directory listings programmatically. This guide walks you through using the Directorist REST API for fetching listings, managing categories, handling pagination, ordering results, filtering with tags, and retrieving specific data.

Base API Endpoint

All Directorist API requests use the following base URL:

https://yourwebsite.com/wp-json/directorist/v1/

Replace yourwebsite.com with your actual site URL where Directorist is installed.

Authentication

Some API endpoints may require authentication. Use WordPress application passwords or JWT authentication for secure access.

1. Fetching Listings

To retrieve all directory listings, use:

GET /wp-json/directorist/v1/listings

Query Parameters

per_page – Number of listings per page (default: 10, max: 100)
page – Pagination (default: 1)
orderby – Order results (e.g., date, title)
order – Sorting order (asc or desc)
search – Search keyword

Example request:

GET /wp-json/directorist/v1/listings?per_page=25&page=2&orderby=date&order=desc

2. Handling Pagination

The API response contains headers for pagination:

X-WP-Total – Total number of listings
X-WP-TotalPages – Total pages

To paginate, check these headers and use the page query parameter:

GET /wp-json/directorist/v1/listings?per_page=25&page=3

3. Filtering Listings by Category

To fetch listings under a specific category, use:

GET /wp-json/directorist/v1/listings?categories=category_id

Example:

GET /wp-json/directorist/v1/listings?categories=1099&per_page=10

To get available categories:

GET /wp-json/directorist/v1/listings/categories

4. Fetching Listings by Location

Retrieve listings from a specific location:

GET /wp-json/directorist/v1/listings?locations=location_id

Example:

GET /wp-json/directorist/v1/listings?locations=530&per_page=15

Get all available locations:

GET /wp-json/directorist/v1/listings/locations

5. Fetching Listings by Tags

Filter listings by tags:

GET /wp-json/directorist/v1/listings?tags=tag_id

Example:

GET /wp-json/directorist/v1/listings?tags=205&per_page=20

Retrieve all tags:

GET /wp-json/directorist/v1/listings/tags

6. Sorting Listings

Order listings using orderby and order parameters:

Available `orderby` values:

date – Order by published date
title – Order by title
modified – Order by last modified date

Example:

GET /wp-json/directorist/v1/listings?orderby=title&order=asc

7. Fetching a Single Listing

Retrieve details of a specific listing by ID:

GET /wp-json/directorist/v1/listings/{id}

Example:

GET /wp-json/directorist/v1/listings/105

8. Fetching Blog Posts

If your directory site has a blog, fetch posts using:

GET /wp-json/wp/v2/posts

With pagination:

GET /wp-json/wp/v2/posts?per_page=10&page=2

Conclusion

Directorist REST API makes it easy to fetch, filter, and manage directory listings efficiently. By leveraging these endpoints, developers can build seamless integrations, enhance search functionalities, and optimize directory experiences.

For advanced API usage, refer to the official Directorist documentation.