Skip to content

List & Search Libraries

List libraries

GET /api/v1/libraries/

Return a paginated list of approved libraries with optional search filters.

Auth required: No

Need the complete catalogue?

Use the authenticated Bulk Download to retrieve every approved library as one reusable GeoJSON artifact. Do not paginate or scrape this endpoint to copy the full catalogue.

Query parameters

Parameter Type Default Description
q string — Free-text search across name and description with full-text ranking (max 200 chars)
search string — Global search across name, description, city, address, and postal code with substring matching (max 200 chars). Takes precedence over q when both are sent.
city string — Filter by city name (case-insensitive, max 100 chars)
country string — Filter by ISO 3166-1 alpha-2 country code (max 2 chars)
postal_code string — Filter by postal / ZIP code (max 20 chars)
has_photo bool — Filter by photo presence: true for libraries with a photo, false for those without
lat float — Latitude for proximity search (-90 to 90, requires lng and radius_km)
lng float — Longitude for proximity search (-180 to 180, requires lat and radius_km)
radius_km int — Search radius in kilometres (1–100, requires lat and lng)
page int 1 Page number (1–1000)
page_size int 20 Items per page (1–50)

Examples

Text search

curl "https://bookcorners.org/api/v1/libraries/?q=corner+books&page_size=5"

import requests

resp = requests.get(
    "https://bookcorners.org/api/v1/libraries/",
    params={"q": "corner books", "page_size": 5},
)
data = resp.json()

Combined search across fields

Use search to match a single term against name, description, city, address, and postal code at once. Name matches are ranked above other field matches when available.

curl "https://bookcorners.org/api/v1/libraries/?search=Berlin"

resp = requests.get(
    "https://bookcorners.org/api/v1/libraries/",
    params={"search": "Berlin"},
)

Filter by city and country

curl "https://bookcorners.org/api/v1/libraries/?city=Berlin&country=DE"

resp = requests.get(
    "https://bookcorners.org/api/v1/libraries/",
    params={"city": "Berlin", "country": "DE"},
)

Find libraries within 5 km of a point:

curl "https://bookcorners.org/api/v1/libraries/?lat=52.52&lng=13.405&radius_km=5"

resp = requests.get(
    "https://bookcorners.org/api/v1/libraries/",
    params={"lat": 52.52, "lng": 13.405, "radius_km": 5},
)

Response (200 OK)

{
  "items": [
    {
      "id": 42,
      "slug": "berlin-friedrichstr-12-corner-books",
      "name": "Corner Books",
      "description": "A cozy community bookcase near the park entrance.",
      "photo_url": "/media/libraries/photos/corner-books.jpg",
      "thumbnail_url": "/media/libraries/thumbnails/corner-books.jpg",
      "lat": 52.52,
      "lng": 13.405,
      "address": "Friedrichstr. 12",
      "city": "Berlin",
      "country": "DE",
      "postal_code": "10117",
      "wheelchair_accessible": "yes",
      "capacity": 50,
      "is_indoor": false,
      "is_lit": true,
      "website": "",
      "contact": "",
      "source": "",
      "operator": "",
      "brand": "Local Book Exchange Network",
      "created_at": "2025-06-15T14:30:00Z",
      "is_favourited": false
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total": 142,
    "total_pages": 8,
    "has_next": true,
    "has_previous": false
  }
}

Rate limiting

This endpoint uses the read rate limit tier. See Rate Limiting.

Latest libraries

GET /api/v1/libraries/latest

Return the most recently approved libraries as a flat list (no pagination).

Auth required: No

Query parameters

Parameter Type Default Description
limit int 10 Number of results (1–50)
has_photo bool — Filter by photo presence: true for libraries with a photo, false for those without 
curl "https://bookcorners.org/api/v1/libraries/latest?limit=5"

resp = requests.get(
    "https://bookcorners.org/api/v1/libraries/latest",
    params={"limit": 5},
)

Response (200 OK)

{
  "items": [
    {
      "id": 42,
      "slug": "berlin-friedrichstr-12-corner-books",
      "name": "Corner Books",
      "description": "A cozy community bookcase near the park entrance.",
      "photo_url": "/media/libraries/photos/corner-books.jpg",
      "thumbnail_url": "/media/libraries/thumbnails/corner-books.jpg",
      "lat": 52.52,
      "lng": 13.405,
      "address": "Friedrichstr. 12",
      "city": "Berlin",
      "country": "DE",
      "postal_code": "10117",
      "wheelchair_accessible": "yes",
      "capacity": 50,
      "is_indoor": false,
      "is_lit": true,
      "website": "",
      "contact": "",
      "source": "",
      "operator": "",
      "brand": "Local Book Exchange Network",
      "created_at": "2025-06-15T14:30:00Z",
      "is_favourited": false
    }
  ]
}