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

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 little free library 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": "Little Free Library",
      "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 little free library 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": "Little Free Library",
      "created_at": "2025-06-15T14:30:00Z",
      "is_favourited": false
    }
  ]
}