GET /listings
List listings
Public listings, newest first. Filter by status, species and place. Sync with updated_since and If-None-Match. An identical request within 60 seconds gets the previous response from the cache.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
status | query | string | Comma-separated: missing, found, seen, home. |
species | query | string | Comma-separated: cat, dog, bird, small_mammal, reptile, horse, other. |
province | query | string | Province slug (see /gemeenten). Not together with gemeente or near. |
gemeente | query | string | Municipality slug or NIS code (see /gemeenten). |
near | query | string | Belgian postcode: listings in municipalities whose centre lies within radius km (distance between municipality centres, never exact locations). |
radius | query | integer 1–25 | Radius in km (1–25, default 10), only with near. |
updated_since | query | string | Only listings changed since then (ISO 8601). The basis of syncing. |
sort | query | string (-reported_at, reported_at, -updated_at, updated_at) = -reported_at | Sort order; a minus sign means newest first. |
page | query | integer 1–100 = 1 | Page (max. 100). For a full sync, use updated_since. |
per_page | query | integer 1–100 = 25 | Results per page (max. 100). |
lang | query | string (nl, fr, en, de) = nl | Language of the labels and links (the link opens the listing in that language). |
If-None-Match | header | string | ETag of your previous response: unchanged → 304 without a body. |
If-Modified-Since | header | string | Last-Modified of your previous response. |
Example request
curl
curl -s "https://ikbenvermist.be/wp-json/ibv/api/v1/listings?status=missing&gemeente=hasselt&lang=nl" \
-H "Authorization: Bearer $IBV_API_KEY" \
-H 'If-None-Match: W/"…"'JavaScript
// on your server (Node 18+), never in the browser
const res = await fetch('https://ikbenvermist.be/wp-json/ibv/api/v1/listings?status=missing&gemeente=hasselt&lang=nl', {
headers: { Authorization: `Bearer ${process.env.IBV_API_KEY}` },
});
if (res.status === 429) { /* wait res.headers.get('Retry-After') seconds */ }
const body = await res.json();PHP
$ch = curl_init('https://ikbenvermist.be/wp-json/ibv/api/v1/listings?status=missing&gemeente=hasselt&lang=nl');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('IBV_API_KEY')],
]);
$body = json_decode(curl_exec($ch), true);Example response 200
{
"data": [
{
"id": 900001,
"status": "missing",
"status_label": "Vermist",
"species": "cat",
"species_label": "Kat",
"place": {
"gemeente": "Hasselt",
"gemeente_slug": "hasselt",
"nis": "71022",
"province": "Limburg",
"province_slug": "limburg"
},
"reported_at": "2026-10-10T08:12:00Z",
"updated_at": "2026-10-11T17:40:00Z",
"url": "https://ikbenvermist.be/m/900001/?utm_source=jouw-organisatie&utm_medium=api&utm_campaign=api",
"links": {
"self": "https://ikbenvermist.be/wp-json/ibv/api/v1/listings/900001",
"html": "https://ikbenvermist.be/m/900001/?utm_source=jouw-organisatie&utm_medium=api&utm_campaign=api",
"gemeente": "https://ikbenvermist.be/?utm_source=jouw-organisatie&utm_medium=api&utm_campaign=api"
}
},
{
"id": 900002,
"status": "found",
"status_label": "Gevonden",
"species": "dog",
"species_label": "Hond",
"place": {
"gemeente": "Gent",
"gemeente_slug": "gent",
"nis": "44021",
"province": "Oost-Vlaanderen",
"province_slug": "oost-vlaanderen"
},
"reported_at": "2026-10-09T14:03:00Z",
"updated_at": "2026-10-09T14:03:00Z",
"url": "https://ikbenvermist.be/m/900002/?utm_source=jouw-organisatie&utm_medium=api&utm_campaign=api",
"links": {
"self": "https://ikbenvermist.be/wp-json/ibv/api/v1/listings/900002",
"html": "https://ikbenvermist.be/m/900002/?utm_source=jouw-organisatie&utm_medium=api&utm_campaign=api",
"gemeente": "https://ikbenvermist.be/?utm_source=jouw-organisatie&utm_medium=api&utm_campaign=api"
}
}
],
"meta": {
"page": 1,
"per_page": 2,
"total": 6,
"total_pages": 3,
"lang": "nl",
"generated_at": "2026-10-15T01:00:02Z"
},
"links": {
"self": "https://ikbenvermist.be/wp-json/ibv/api/v1/listings?lang=nl&per_page=2&page=1",
"first": "https://ikbenvermist.be/wp-json/ibv/api/v1/listings?lang=nl&per_page=2&page=1",
"last": "https://ikbenvermist.be/wp-json/ibv/api/v1/listings?lang=nl&per_page=2&page=3",
"next": "https://ikbenvermist.be/wp-json/ibv/api/v1/listings?lang=nl&per_page=2&page=2",
"docs": "https://ikbenvermist.be/en/api/documentation/"
}
}