geodirectory/list-listings searches and filters directory listings: keyword, status, author, categories, tags and sorting.
With Location Manager active it also does proximity search, which is the thing a directory is actually for.
At a glance
| Ability | geodirectory/list-listings |
| Toolset | GeoDirectory — toolset/geodirectory |
| Group | GeoDirectory › Listings |
| Requires | AcrossAI Pro, plus GeoDirectory active on the site |
| Capability | manage_options |
| Safety | Read-only — changes nothing |
| Repeatable | Idempotent — running it twice leaves the same result |
| Ships in | AcrossAI Pro 0.9.16 and later |
How it works
Proximity search takes either near — an address, or the literal me to use the caller’s IP — or a latitude and longitude pair, together with a distance radius. Sorting by distance needs the same.
All of that belongs to the Location Manager add-on. Without it, those parameters are ignored with a warning rather than refused — the search still runs and returns results that are not filtered by location at all.
That is the behaviour to know about, because unfiltered results look like a working search on a site where nothing is nearby.
The distance unit is the site’s configured one rather than a fixed measure, and the default radius is the site search radius rather than unlimited.
Every listing comes back with all of its custom fields, so a search result is usable without a read per row.
Input
| Name | Type | Required | What it is |
|---|---|---|---|
post_type | string | No | Listing type, for example gd_place. Defaults to the site default. See geodirectory/get-directory-overview for the valid values. |
search | string | No | Free-text keyword search. |
status | string | No — defaults to publish | Post status filter. |
author | integer | No | Only listings owned by this user. |
categories | array | No | Category term IDs. |
tags | array | No | Tag term IDs. |
near | string | Location Manager only | An address to search near, or me to use the caller’s IP. |
latitude | number | Location Manager only | Latitude. Pair with longitude. |
longitude | number | Location Manager only | Longitude. Pair with latitude. |
distance | number | Location Manager only | Search radius in the site’s distance unit. Defaults to the site search radius. |
country | string | Location Manager only | Country slug or name. |
region | string | Location Manager only | Region slug or name. |
city | string | Location Manager only | City slug or name. |
neighbourhood | string | Location Manager only, with neighbourhoods enabled | Neighbourhood slug or name. |
orderby | string | No | Sort key, for example post_date_desc or overall_rating_desc. distance needs Location Manager plus coordinates. |
order | string | No | Sort direction. |
per_page | integer | No | Rows per page. |
page | integer | No | Page number. |
What comes back
| Name | Type | What it is |
|---|---|---|
listings | array | Each listing with all of its custom fields. |
total | integer | How many matched. |
success | boolean | Whether the call completed. |
message | string | A one-line summary of what happened, suitable for showing a human. |
error_code | string | Present only on failure — a stable machine-readable reason, such as a missing field, a wrong field type or an unmet confirmation. |
Example
Ask your assistant:
Find restaurants within five miles of the station.
It resolves to one call:
{
"ability": "geodirectory/list-listings",
"parameters": {
"near": "Bristol Temple Meads",
"distance": 5,
"orderby": "distance"
}
}Worth knowing
- Location parameters are ignored, not refused, without Location Manager.
- Unfiltered results look like a working search with nothing nearby.
- The distance unit is the site’s, not miles by default.
- Custom fields come back on every row.
Related abilities
- GeoDirectory Overview — check the add-ons first
- GeoDirectory Get Listing — one listing in full
- GeoDirectory List Locations — the location filters
Get the plugins:
AcrossAI Abilities Manager · AcrossAI MCP Manager
Browse the rest: Every ability, by category