History API

Events, Births and Deads

Navigation

Overview

Base URL
https://historyapi.dev/api/v1
Authentication

Requests do not currently require any Authorization header

Response Format

All responses are returned in JSON-LD format (application/ld+json). It can be consumed like regular JSON, but also includes semantic metadata (e.g., @context, @id, @type) for linked data support.

Pagination

Collection endpoints support pagination with the following parameters:

  • page: Page number (default: 1)
  • itemsPerPage: Items per page (default: 20, maximum: 100)
Swagger docs

If you prefer, you can view the Swagger documentation.

Events API

GET /events

Retrieves a collection of historical events

Query Parameters
Parameter Type Required Description
year integer Optional Event year (exact match)
month integer Optional Event month (1-12, exact match)
day integer Optional Event day (1-31, exact match)
type string Optional Event type: event, birth, death
lang string Optional Event language: en
text string Optional Partial search in event text
page integer Optional Page number (default: 1)
itemsPerPage integer Optional Items per page (default: 20, maximum: 100)
Request Example
GET https://historyapi.dev/api/v1/events?lang=en
Response Example
{
  "@context": "/v1/contexts/Event",
  "@id": "/v1/events",
  "@type": "hydra:Collection",
  "hydra:totalItems": 138366,
  "hydra:member": [
    {
      "@id": "/v1/events/1",
      "@type": "Event",
      "id": 12812,
      "year": 1969,
      "month": 7,
      "day": 20,
      "text": "Apollo 11 lands on the Moon",
      "type": "event",
      "lang": "en",
      "active": true,
    }
    {...}
  ],
  "hydra:view": {
    "@id": "/v1/events?page=2",
    "@type": "hydra:PartialCollectionView"
    "first": "/api/v1/events?page=1",
    "last": "/api/v1/events?page=6918",
    "previous": "/api/v1/events?page=1",
    "next": "/api/v1/events?page=3"
  }
}
POST /events

Creates a new historical event

Body Parameters (JSON)
Field Type Required Description
year integer Required Event year
month integer Required Event month (1-12)
day integer Required Event day (1-31)
text string (text) Required Event description
type string Required Type: event, birth or death
lang string Required Language: en
Request Example
{
  "year": 1969,
  "month": 7,
  "day": 20,
  "text": "Apollo 11 lands on the Moon",
  "type": "event",
  "lang": "en"
}
Response Example (201 Created)
{
  "@context": "/v1/contexts/Event",
  "@id": "/v1/events/1",
  "@type": "Event",
  "id": 1,
  "year": 1969,
  "month": 7,
  "day": 20,
  "text": "Apollo 11 lands on the Moon",
  "type": "event",
  "lang": "en",
  "active": false
}
Note: New events are created with active: false by default and require administrative approval.

Reports API

POST /reports

Creates a report about an event

Body Parameters (JSON)
Field Type Required Description
targetId integer Required ID of the event to report
reason string (max: 255) Required Reason for the report
text string (max: 255) Required Detailed description of the issue
email string (max: 255) Required Reporter's contact email
Request Example
{
  "targetId": 123,
  "reason": "Incorrect information",
  "text": "The date of this event is wrong. It should be July 21, not July 20.",
  "email": "user@example.com"
}
Response Example (201 Created)
{
  "@context": "/v1/contexts/Report",
  "@id": "/v1/reports/1",
  "@type": "Report",
  "id": 1
}

Filters

Search Filter

Allows searching by specific fields with different strategies:

Field Strategy Description Example
year exact Exact match ?year=1969
month exact Exact match ?month=7
day exact Exact match ?day=20
type exact Exact match ?type=event
lang exact Exact match ?lang=en
text partial Partial search (LIKE %text%) ?text=Apollo
Range Filter

Allows filtering by numeric ranges using operators:

Operator Description Example
[gt] Greater than ?year[gt]=1900
[gte] Greater than or equal ?year[gte]=1900
[lt] Less than ?year[lt]=2000
[lte] Less than or equal ?year[lte]=2000
[between] Between two values ?year[between]=1900..2000
Usage examples:
# Events after 1950
GET /v1/events?year[gt]=1950

# Events between 1900 and 2000
GET /v1/events?year[between]=1900..2000

# Events from the 20th century
GET /v1/events?year[gte]=1900&year[lt]=2000
Combining Filters

You can combine multiple filters in a single request:

# Births in July between 1940 and 1960
GET /v1/events?type=birth&month=7&year[between]=1940..1960

# Events containing "moon" in text from the 20th century
GET /v1/events?text=moon&year[gte]=1900&year[lt]=2000

# Deaths in 1969
GET /v1/events?type=death&year=1969

Rate Limits

The API implements rate limiting using the Token Bucket strategy to prevent abuse:

Per Second Limit
  • Limit: 500 requests
  • Refill: 200 requests/second
  • Interval: 1 second
Per Minute Limit
  • Limit: 10,000 requests
  • Refill: 10,000 requests/minute
  • Interval: 1 minute
Information: If you exceed these limits, you will receive a 429 Too Many Requests response. Limits reset automatically according to the specified intervals.

CORS (Cross-Origin Resource Sharing)

The API has CORS configured to allow requests from any domain:

Configuration Value
Allowed Origins All domains (*)
Allowed Methods GET, OPTIONS, POST
Allowed Headers Content-Type, Authorization
Exposed Headers Link
Max Age 3600 seconds (1 hour)
Note: The CORS configuration allows requests from any domain, making the API accessible from web applications hosted anywhere.

HTTP Status Codes

Code Description
200 OK - Successful request
201 Created - Resource successfully created
400 Bad Request - Request error (invalid parameters)
404 Not Found - Resource not found
422 Unprocessable Entity - Validation error
429 Too Many Requests - Rate limit exceeded
500 Internal Server Error - Server error