API docs

A free, open read-only HTTP API for Philippine Supreme Court decisions. No API key. No login. No monthly limit. Please cache responses where you can and don't hammer the endpoints — this runs on free-tier infrastructure and is funded out of pocket.

Base URL

https://<your-deploy-host>/api/v1

Rate limits

Search: 30 requests per minute per IP (in-memory, best-effort)
Research assistant: 10 requests per minute per IP, and subject to a daily OpenAI spend cap
All other endpoints: unthrottled but please be polite

License

Code: MIT
Structured corpus (titles, doctrines, summaries, metadata extracted by AI): CC BY-SA 4.0 — attribute LegalSearch PH and link back
Original decision text belongs to the Supreme Court of the Philippines and is in the public domain

Endpoints

GET/api/v1/stats

Example

/api/v1/stats

Returns

Corpus size, source breakdown, coverage date range, citation graph stats, license.

GET/api/v1/search

Param	Type	Description
q	string (required)	Natural language query or exact terms
limit	int (default 10, max 50)	Results to return
year	int	Filter by promulgation year
topic	string	Filter by topic category
division	string	En Banc \| First Division \| Second Division \| Third Division
ponente	string	Justice surname

Example

/api/v1/search?q=warrantless+search&limit=5

Returns

{ q, year, topic, division, ponente, count, results: Case[] } where each Case includes id, title, gr_number, date, summary, doctrine, source_url, topics, division, ponente, authority_score, similarity.

POST/api/v1/search

Example

curl -X POST -H "content-type: application/json" -d '{"q":"plunder"}' https://YOUR-HOST/api/v1/search

Returns

Same shape as GET. Use POST if your query has awkward URL characters.

GET/api/v1/cases/:id

Example

/api/v1/cases/3

Returns

{ case: { id, title, gr_number, date, summary, doctrine, source_url, division, ponente, topics, disposition, dispositive, statutes, vote, separate_count, authority_score } }

GET/api/v1/cases/:id/citations

Example

/api/v1/cases/3/citations

Returns

{ cites: [{ label, target_gr, target }], cited_by: Case[] } — forward and reverse edges in the citation graph.

GET/api/v1/cases/:id/related

Example

/api/v1/cases/3/related

Returns

{ results: Case[] } — top 5 semantically similar cases via embedding cosine distance.

GET/api/v1/top-cases

Param	Type	Description
limit	int (default 50, max 200)	Results to return
year	int	Filter by year
topic	string	Filter by topic category

Example

/api/v1/top-cases?topic=Constitutional+Law&limit=20

Returns

{ count, year, topic, results: Case[] } sorted by authority_score descending.

GET/api/v1/years

Example

/api/v1/years

Returns

{ years: int[] } — all years present in the corpus, newest first.

GET/api/v1/topics

Example

/api/v1/topics

Returns

{ topics: { name, count }[] } — topic taxonomy with case counts.

GET/api/v1/meta

Example

/api/v1/meta

Returns

{ divisions: { name, count }[], ponentes: { name, count }[] } — divisions by count, ponentes alphabetical.