Gutensearch API Documentation

To use the API, you'll need an API key. Request an API key here

Base URL

https://gutensearch.toolforge.org/api/v1

Authentication

All API requests require authentication using an API key. You can provide your API key in two ways:

Method 1: Authorization Header (Recommended)

Include your API key in the Authorization header with the Bearer prefix: 

curl -H "Authorization: Bearer your_api_key_here" \\
  "https://gutensearch.toolforge.org/api/v1/search?q=shakespeare"

Method 2: Query Parameter

Include your API key as an api_key query parameter: 

curl "https://gutensearch.toolforge.org/api/v1/search?q=shakespeare&api_key=your_api_key_here"

Endpoints

GET /api/v1/search

Search for Project Gutenberg texts using full-text search. Supports exact phrase matching across titles and full text content.

Query Parameters

Parameter Type Required Description
q String Required The search query. Searches for exact phrases in book titles and full text.
api_key String Conditional Your API key (required if not using Authorization header)
page Integer Optional Page number for pagination (default: 0)
per_page Integer Optional Results per page (default: 50, max: 50)
language String Optional Filter results by language code (e.g., "en", "fr", "de")

Response Format

The API returns JSON with the following structure:

{
  "query": "shakespeare",
  "total_results": 150,
  "page": 0,
  "per_page": 50,
  "total_pages": 3,
  "results": [
    {
      "text_id": "pg1234",
      "type": "Text",
      "issued": "2024-01-15",
      "title": "The Complete Works of William Shakespeare",
      "language": "en",
      "authors": ["Shakespeare, William"],
      "subjects": ["Drama", "Poetry"],
      "locc": ["PR"],
      "bookshelves": ["British Literature"],
      "file_size": 1234567,
      "highlights": {
        "title": ["The Complete Works of William Shakespeare"],
        "fulltext": [
          "To be or not to be, that is the question...",
          "All the world's a stage..."
        ]
      }
    }
  ]
}

Response Fields

Field Type Description
query String The search query that was executed
total_results Integer Total number of matching results
page Integer Current page number (zero-indexed)
per_page Integer Number of results per page
total_pages Integer Total number of pages available
results Array Array of search result objects
results[].text_id String Project Gutenberg text identifier
results[].type String Type of document (e.g., "Text")
results[].issued String Publication date (ISO 8601 format)
results[].title String Book title
results[].language String Language code (e.g., "en" for English)
results[].authors Array List of author names
results[].subjects Array List of subject classifications
results[].locc Array Library of Congress Classification codes
results[].bookshelves Array Project Gutenberg bookshelf categories
results[].file_size Integer File size in bytes
results[].highlights Object Highlighted search matches with <em> tags around matched terms

Example Requests

# Using Authorization header
curl -H "Authorization: Bearer your_api_key_here" \\
  "https://gutensearch.toolforge.org/api/v1/search?q=to%20be%20or%20not%20to%20be&page=0&per_page=10"

# Or using query parameter
curl "https://gutensearch.toolforge.org/api/v1/search?q=to%20be%20or%20not%20to%20be&page=0&per_page=10&api_key=your_api_key_here"

# Filter by language
curl -H "Authorization: Bearer your_api_key_here" \\
  "https://gutensearch.toolforge.org/api/v1/search?q=Molière&language=fr"

Example Response (Success)

{
  "query": "to be or not to be",
  "total_results": 12,
  "page": 0,
  "per_page": 10,
  "total_pages": 2,
  "results": [
    {
      "text_id": "pg1524",
      "type": "Text",
      "issued": "1998-12-01",
      "title": "Hamlet",
      "language": "en",
      "authors": ["Shakespeare, William"],
      "subjects": ["Tragedy", "Drama"],
      "locc": ["PR"],
      "bookshelves": ["Plays"],
      "file_size": 189432,
      "highlights": {
        "fulltext": [
          "To be or not to be, that is the question..."
        ]
      }
    }
  ]
}

Error Responses

Error Format

All errors return a JSON response with an error message:

{
  "error": "Error message here"
}

Common Error Codes

Status Code Description Example
400 Bad Request Missing or invalid query parameter {"error": "Search query parameter 'q' is required"}
401 Unauthorized Missing or invalid API key {"error": "Invalid API key"}
500 Internal Server Error Server error during search {"error": "An error occurred while searching. Please try again."}
503 Service Unavailable Search index not available {"error": "Search index not found. Please contact administrator."}

Rate Limiting

Note: Rate limiting policies are managed per API key. Contact support for information about your specific rate limits.

Best Practices

  • Use exact phrases for more precise results
  • Implement pagination for large result sets
  • Cache results when appropriate to reduce API calls
  • Handle errors gracefully in your application
  • Include proper error handling for all API responses

Support

For questions or issues with the API:

  • Check this documentation for common usage patterns
  • Request an API key if you haven't already
  • Contact your administrator for technical support
Back to Home