API Documentation

Access library hours data programmatically with our RESTful API

Introduction

The Library Hours 24 API provides programmatic access to our comprehensive library database. With our API, you can:

  • Search for libraries by name, location, or type
  • Get detailed library information including hours and services
  • Check real-time open/closed status
  • Find nearby libraries based on coordinates
  • Access data for over 1000 libraries worldwide

Base URL

https://api.libraryhours24.com/v1

Response Format

All API responses are returned in JSON format with UTF-8 encoding.

Authentication

The Library Hours 24 API uses API keys to authenticate requests. You can request an API key by contacting us.

Getting Your API Key

  1. Contact us at amywerson@gmail.com
  2. Provide your application name and intended use
  3. Receive your unique API key within 24-48 hours

Using Your API Key

Include your API key in the request header:

X-API-Key: YOUR_API_KEY

Or as a query parameter:

GET /libraries?api_key=YOUR_API_KEY

API Endpoints

GET /libraries

Retrieve a list of all libraries with pagination support.

Query Parameters

Parameter Type Description Required
page integer Page number (default: 1) Optional
limit integer Results per page (max: 100, default: 20) Optional
country string Filter by country code (e.g., US, UK, FR) Optional
type string Filter by library type (public, university, national) Optional

Example Response

{ "success": true, "data": { "libraries": [ { "id": "lib_001", "name": "New York Public Library - Main Branch", "type": "public", "address": "476 5th Ave, New York, NY 10018", "coordinates": { "lat": 40.7532, "lng": -73.9822 }, "hours": { "monday": "10:00-20:00", "tuesday": "10:00-20:00", "wednesday": "10:00-20:00", "thursday": "10:00-20:00", "friday": "10:00-18:00", "saturday": "10:00-18:00", "sunday": "13:00-17:00" }, "status": "open", "services": ["wifi", "computers", "printing", "study_rooms"] } ], "pagination": { "page": 1, "limit": 20, "total": 1000, "pages": 50 } } }
GET /libraries/{id}

Get detailed information about a specific library.

Path Parameters

Parameter Type Description Required
id string Library ID Required
GET /libraries/search

Search for libraries by name or location.

Query Parameters

Parameter Type Description Required
q string Search query Required
lat float Latitude for location-based search Optional
lng float Longitude for location-based search Optional
radius integer Search radius in kilometers (default: 10) Optional
GET /libraries/{id}/status

Get real-time open/closed status for a library.

Example Response

{ "success": true, "data": { "library_id": "lib_001", "status": "open", "current_time": "2025-01-09T14:30:00Z", "closes_at": "20:00", "opens_at": null, "message": "Open until 8:00 PM" } }

Rate Limits

API Rate Limits:
  • Free tier: 1,000 requests per day
  • Basic plan: 10,000 requests per day
  • Pro plan: 100,000 requests per day
  • Enterprise: Unlimited (contact us)

Rate limit information is included in response headers:

X-RateLimit-Limit: 1000 X-RateLimit-Remaining: 999 X-RateLimit-Reset: 1640995200

Error Handling

The API uses standard HTTP status codes to indicate success or failure.

Status Codes

Code Status Description
200 OK Request successful
400 Bad Request Invalid request parameters
401 Unauthorized Invalid or missing API key
404 Not Found Resource not found
429 Too Many Requests Rate limit exceeded
500 Internal Server Error Server error

Error Response Format

{ "success": false, "error": { "code": "RESOURCE_NOT_FOUND", "message": "Library with ID 'lib_999' not found", "details": null } }

Code Examples

JavaScript (Fetch API)

const apiKey = 'YOUR_API_KEY'; const baseUrl = 'https://api.libraryhours24.com/v1'; // Search for libraries async function searchLibraries(query) { const response = await fetch(`${baseUrl}/libraries/search?q=${query}`, { headers: { 'X-API-Key': apiKey } }); if (!response.ok) { throw new Error(`HTTP error! status: ${response.status}`); } const data = await response.json(); return data; } // Get library by ID async function getLibrary(id) { const response = await fetch(`${baseUrl}/libraries/${id}`, { headers: { 'X-API-Key': apiKey } }); const data = await response.json(); return data; } // Usage searchLibraries('Boston Public Library') .then(data => console.log(data)) .catch(error => console.error('Error:', error));

Python (Requests)

import requests api_key = 'YOUR_API_KEY' base_url = 'https://api.libraryhours24.com/v1' headers = { 'X-API-Key': api_key } # Search for libraries def search_libraries(query): response = requests.get( f'{base_url}/libraries/search', params={'q': query}, headers=headers ) response.raise_for_status() return response.json() # Get library by ID def get_library(library_id): response = requests.get( f'{base_url}/libraries/{library_id}', headers=headers ) response.raise_for_status() return response.json() # Usage try: results = search_libraries('New York Public Library') print(results) except requests.exceptions.RequestException as e: print(f'Error: {e}')

cURL

# Search for libraries curl -X GET "https://api.libraryhours24.com/v1/libraries/search?q=library" \ -H "X-API-Key: YOUR_API_KEY" # Get specific library curl -X GET "https://api.libraryhours24.com/v1/libraries/lib_001" \ -H "X-API-Key: YOUR_API_KEY" # Get library status curl -X GET "https://api.libraryhours24.com/v1/libraries/lib_001/status" \ -H "X-API-Key: YOUR_API_KEY"

SDKs & Libraries

We provide official SDKs for popular programming languages to make integration easier.

JavaScript/Node.js

Official npm package

npm install libraryhours24

Python

Official PyPI package

pip install libraryhours24

PHP

Composer package

composer require libraryhours24/api

Ruby

RubyGems package

gem install libraryhours24

Need Help?

Contact our developer support team at amywerson@gmail.com or visit our contact page.