> For the complete documentation index, see [llms.txt](https://mobile-calendar.gitbook.io/v1/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://mobile-calendar.gitbook.io/v1/rest-api/statistics.md).

# Statistics

Period statistics (occupancy, income, reservations) calculated like the panel's Statistics module.

## Period statistics: occupancy, income, reservations — the same numbers as the panel's Statistics module

> Occupancy, income and reservation counts for a period, calculated exactly like the panel's Statistics module (panel → Statistics and reports → Statistics). USE THIS for any question about occupancy, income/revenue/turnover, ADR, RevPAR, number of reservations or average stay in a period — do not compute these yourself from reservation lists (different definitions give different numbers). Definitions: \`occupancy.percent\` = reservation nights in the period / (active rooms × days of the period); date blocks are neither sold nights nor subtracted from the available nights (unless the account treats blocks as reservations — \`blockadesCountedAsReservations\`). \`revenue\[].income\` = reservation amount (room + meals + services − discount) spread evenly over the nights and counted for the nights inside the period (the panel's "Income"); \`paid\` / \`toPay\` by payment status, same proration; a group reservation is split between its rooms. \`reservations\` = reservations overlapping the period (a group counts once). \`perRoom\` = the room table of the module. Amounts per currency. Required scope: \`statistics.read\` (employees: permission "Statistics" — without it the panel blocks the module and so must you).

```json
{"openapi":"3.0.0","info":{"title":"Public REST API v1 – mobile-calendar.com","version":"1.0.0"},"tags":[{"name":"statistics","description":"Period statistics (occupancy, income, reservations) calculated like the panel's Statistics module."}],"servers":[{"url":"https://api.mobile-calendar.com/v1/public","description":"Production"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","description":"Pass the token in header: Authorization: Bearer <JWT>","bearerFormat":"JWT","scheme":"bearer"}},"schemas":{"StatisticsResponse":{"required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/Statistics"},"meta":{"$ref":"#/components/schemas/MetaWithRuid"}},"type":"object"},"Statistics":{"required":["from","to","days","rooms","occupancy","guestOccupancy","reservations","adults","children","averageLengthOfStay","revenue","perRoom","blockadesCountedAsReservations"],"properties":{"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"},"days":{"type":"integer"},"rooms":{"description":"Active rooms counted","type":"integer"},"occupancy":{"description":"Room occupancy — the panel's \"Occupancy\"","properties":{"percent":{"type":"number","format":"float"},"nightsSold":{"type":"integer"},"nightsAvailable":{"description":"rooms × days (date blocks are not subtracted)","type":"integer"}},"type":"object"},"guestOccupancy":{"description":"Occupancy of beds (guests vs room capacity)","properties":{"percent":{"type":"number","format":"float"},"guestNights":{"type":"number","format":"float"},"capacity":{"type":"integer"}},"type":"object"},"reservations":{"description":"Reservations overlapping the period (group counted once)","type":"number","format":"float"},"adults":{"type":"number","format":"float"},"children":{"type":"number","format":"float"},"averageLengthOfStay":{"description":"Nights","type":"number","format":"float"},"revenue":{"description":"Per currency","type":"array","items":{"properties":{"currency":{"type":"string"},"income":{"description":"The panel's \"Income\" for the period","type":"number","format":"float"},"paid":{"type":"number","format":"float"},"toPay":{"type":"number","format":"float"},"breakdown":{"properties":{"room":{"type":"number","format":"float"},"meals":{"type":"number","format":"float"},"additionalServices":{"type":"number","format":"float"},"discount":{"type":"number","format":"float"}},"type":"object"},"reservations":{"type":"number","format":"float"},"nightsSold":{"description":"Nights in the period sold in this currency","type":"integer"},"adr":{"description":"Average daily rate: income / nights sold in this currency","type":"number","format":"float","nullable":true},"revPAR":{"description":"income / rooms (as in the panel)","type":"number","format":"float","nullable":true}},"type":"object"}},"perRoom":{"type":"array","items":{"properties":{"roomId":{"type":"integer"},"name":{"type":"string"},"nightsSold":{"type":"integer"},"nightsAvailable":{"type":"integer"},"occupancyPercent":{"type":"number","format":"float"},"reservations":{"type":"integer"},"income":{"type":"object","additionalProperties":{"type":"number"}}},"type":"object"}},"blockadesCountedAsReservations":{"description":"Setting \"treat date blocks as reservations\" of the current user","type":"boolean"}},"type":"object"},"MetaWithRuid":{"description":"Metadata with request tracking.","required":["ruid"],"properties":{"ruid":{"description":"Request Unique ID","type":"string","format":"uuid"}},"type":"object"},"ApiProblem401":{"description":"Missing authentication or invalid credentials.","allOf":[{"$ref":"#/components/schemas/ApiProblemBase"},{"properties":{"type":{"description":"401 Unauthorized","type":"string","format":"uri"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"type":"object"}]},"ApiProblemBase":{"description":"RFC 7807 Problem Details (base schema).","required":["type","title","status","detail","instance"],"properties":{"type":{"description":"RFC 7807 base — DO NOT use directly in endpoints.\nIn endpoints reference ApiProblem400/401/403/409/422/429/500.","type":"string","format":"uri"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"type":"object"},"ApiProblem403":{"description":"Authenticated user but no access.","allOf":[{"$ref":"#/components/schemas/ApiProblemBase"},{"properties":{"type":{"description":"403 Forbidden","type":"string","format":"uri"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"type":"object"}]},"ApiProblem422":{"description":"Input data validation error.","allOf":[{"$ref":"#/components/schemas/ApiProblemBase"},{"properties":{"type":{"description":"422 Unprocessable Entity (validation)","type":"string","format":"uri"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"errors":{"description":"Map: field name → error message(s)","type":"object","additionalProperties":{"$ref":"#/components/schemas/ErrorValue"}}},"type":"object"}]},"ErrorValue":{"description":"Single error message or list of messages.","oneOf":[{"description":"Error value in error map can be:\n- single string, or\n- array of strings (multiple messages for one field).","type":"string"},{"type":"array","items":{"type":"string"}}]}}},"paths":{"/statistics":{"get":{"tags":["statistics"],"summary":"Period statistics: occupancy, income, reservations — the same numbers as the panel's Statistics module","description":"Occupancy, income and reservation counts for a period, calculated exactly like the panel's Statistics module (panel → Statistics and reports → Statistics). USE THIS for any question about occupancy, income/revenue/turnover, ADR, RevPAR, number of reservations or average stay in a period — do not compute these yourself from reservation lists (different definitions give different numbers). Definitions: `occupancy.percent` = reservation nights in the period / (active rooms × days of the period); date blocks are neither sold nights nor subtracted from the available nights (unless the account treats blocks as reservations — `blockadesCountedAsReservations`). `revenue[].income` = reservation amount (room + meals + services − discount) spread evenly over the nights and counted for the nights inside the period (the panel's \"Income\"); `paid` / `toPay` by payment status, same proration; a group reservation is split between its rooms. `reservations` = reservations overlapping the period (a group counts once). `perRoom` = the room table of the module. Amounts per currency. Required scope: `statistics.read` (employees: permission \"Statistics\" — without it the panel blocks the module and so must you).","operationId":"getStatistics","parameters":[{"name":"from","in":"query","description":"First day of the period (inclusive)","required":true,"schema":{"type":"string","format":"date"}},{"name":"to","in":"query","description":"Last day of the period (INCLUSIVE — for September send 2026-09-30); max 731 days","required":true,"schema":{"type":"string","format":"date"}},{"name":"roomId","in":"query","description":"Only these rooms (panel: room filter); omitted = all active rooms","required":false,"style":"form","explode":true,"schema":{"type":"array","items":{"type":"integer"}}}],"responses":{"200":{"description":"Statistics of the period","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatisticsResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiProblem401"}}}},"403":{"description":"Insufficient scope (no access to the Statistics module)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiProblem403"}}}},"422":{"description":"Validation error — missing/invalid dates, period too long, invalid roomId","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiProblem422"}}}}}}}}}
```