The Plannings API provides access to planning metadata and hierarchical structures.
List all plannings
Retrieve the complete list of available university plannings.
Response
Returns a nested object organized by host (university domain):
{
"enscr": {
"title": "ENSCR",
"group": "Rennes",
"host": "enscr",
"children": [
{
"id": "cycleingenieur",
"fullId": "enscr.cycleingenieur",
"title": "Cycle Ingénieur",
"children": [
{
"id": "1iereanneeci",
"fullId": "enscr.cycleingenieur.1iereanneeci",
"title": "1ière année CI",
"children": [...]
}
]
}
]
},
"fac-de-sciences": {
"title": "Faculté des Sciences",
"group": "Rennes",
"host": "fac-de-sciences",
"children": [...]
}
}
Planning tree for a specific university.Show Planning object fields
Display name of the university
Geographic grouping (usually city or region)
Nested planning groups and leaf plannings
Dot-separated full ID (e.g., enscr.cycleingenieur.1iereanneeci)
ICS feed URL. Only present on leaf nodes (actual plannings).
Nested sub-groups (if not a leaf node)
Example request
curl https://planningsup.app/api/plannings
Get planning by ID
Retrieve a specific planning by its full ID.
GET /api/plannings/:fullId
Path parameters
Full planning ID with dot-separated hierarchy.Example: enscr.cycleingenieur.1iereanneeci.elevesing1iereannee
Query parameters
Set to "true" to include calendar events in the response.GET /api/plannings/enscr.elevesing1iereannee?events=true
false, returns only planning metadata. Response (without events)
When events=false or omitted:
{
"id": "elevesing1iereannee",
"fullId": "enscr.cycleingenieur.1iereanneeci.elevesing1iereannee",
"title": "Elèves Ing. 1ière année"
}
Planning ID (last segment of fullId)
Complete dot-separated ID
Response (with events)
When events=true, see the Events API documentation for the complete response structure.
Example requests
curl https://planningsup.app/api/plannings/enscr.elevesing1iereannee
Error responses
Planning not found
{
"error": "Planning not found"
}
404 Not Found
Cause: The specified fullId doesn’t exist in the planning database.
If the fullId is malformed or empty, the API returns a generic error.
Understanding full IDs
Full IDs are constructed by joining all parent IDs with dots:
[host].[level1].[level2].[...].[leafId]
ENSCR (host: enscr)
└─ Cycle Ingénieur (id: cycleingenieur)
└─ 1ière année CI (id: 1iereanneeci)
└─ Elèves Ing. 1ière année (id: elevesing1iereannee)
enscr.cycleingenieur.1iereanneeci.elevesing1iereannee
Use cases
Building a planning selector
Checking if planning exists
Discovering available universities
Fetch all plannings and render a hierarchical selector:const plannings = await client.api.plannings.index.get()
// Render nested structure
function renderTree(node) {
if (node.url) {
// Leaf node - actual planning
return <option value={node.fullId}>{node.title}</option>
} else {
// Group node - render children
return (
<optgroup label={node.title}>
{node.children.map(renderTree)}
</optgroup>
)
}
}
Verify a planning ID before fetching events:try {
const response = await client.api.plannings[fullId].get()
if (response.status === 200) {
console.log('Planning exists:', response.data.title)
}
} catch (error) {
console.error('Planning not found')
}
List all universities and their groups:const plannings = await client.api.plannings.index.get()
for (const [host, data] of Object.entries(plannings.data)) {
console.log(`${data.title} (${data.group})`)
console.log(` Available groups: ${data.children.length}`)
}
Next steps
Events API
Fetch calendar events from plannings
Adding universities
Learn how to add new planning sources