API Reference

The Poetmap REST API gives you programmatic access to poets, their geographic locations, and their published works. All responses are JSON.

Introduction

The base URL for all endpoints is:

https://poermap.veillax.com/api

Authentication

Public read endpoints (GET requests on /api/poets, /api/locations, and /api/works) work without a token, but are subject to a stricter IP-based rate limit.

To get a higher limit, obtain a personal API token from your Account page, then pass it as a Bearer token in the Authorization header:

Authorization: Bearer pm_your_token_here

Example — curl

curl https://poermap.veillax.com/api/poets \
  -H "Authorization: Bearer pm_your_token_here"

Example — JavaScript (fetch)

const res = await fetch('https://poermap.veillax.com/api/poets', {
  headers: {
    'Authorization': 'Bearer pm_your_token_here'
  }
});
const poets = await res.json();

Example — Python (requests)

import requests

resp = requests.get(
    'https://poermap.veillax.com/api/poets',
    headers={'Authorization': 'Bearer pm_your_token_here'}
)
poets = resp.json()

Rate limits

Limits apply per 15-minute sliding window. Responses include headers so you can track your current usage:

When you exceed the limit, the API responds with HTTP 429:

{
  "error":     "Rate limit exceeded",
  "limit":     300,
  "remaining": 0,
  "reset_at":  "2025-04-16T14:30:00.000Z"
}

Errors

Errors follow a consistent shape. The error field is always a human-readable string; some errors include a hint field with remediation advice.

{ "error": "Poet not found" }
{ "error": "Missing API token", "hint": "Pass your token as: Authorization: Bearer pm_..." }

Poets

A poet object contains basic biographical metadata.

{
  "id":        1,
  "name":      "Emily Dickinson",
  "bio":       "...",
  "image_url": "https://...",
  "wiki_url":  "https://en.wikipedia.org/wiki/Emily_Dickinson"
}

Locations

A location is a geographic point associated with a poet — birthplace, residence, place of death, etc.

{
  "id":            12,
  "poet_id":       1,
  "location_type": "birth",
  "place_name":    "Amherst, Massachusetts",
  "lat":           42.3732,
  "lng":           -72.5199
}

Works

A work is a published piece — collection, chapbook, poem — tied to a poet.

{
  "id":          7,
  "poet_id":     1,
  "title":       "Poems by Emily Dickinson",
  "year":        1890,
  "description": "...",
  "url":         "https://..."
}