# Locations

## GET /locations

> List of accessible locations

```json
{"openapi":"3.0.0","info":{"title":"Occuspace Customer API","version":"2.0.0"},"servers":[{"url":"https://api.occuspace.io/v2"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"LocationsResponse":{"type":"object","required":["data","pagination"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Location"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}},"Location":{"type":"object","required":["location_id","name","status","parent_id","capacity","start_date"],"properties":{"location_id":{"type":"integer","description":"ID of the location.  Can be used on other endpoints for specific resources on the location in question."},"name":{"type":"string","description":"Name of the location."},"status":{"type":"string","enum":["active","inactive","setup","review","calibration"],"description":"Current status of this location."},"parent_id":{"type":"integer","nullable":true,"description":"ID of the parent location. Null if it is the root location."},"capacity":{"type":"integer","description":"Capacity of the location (includes the sum of all children locations if applicable)."},"start_date":{"type":"string","format":"date","nullable":true,"description":"Date string to indicate the earliest measured data.  Null if no data has been captured for this location."}}},"Pagination":{"type":"object","required":["prev_cursor","next_cursor","has_more"],"properties":{"prev_cursor":{"type":"string","nullable":true},"next_cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}},"ErrorResponse":{"type":"object","required":["type","title","status","detail","instance","request_id"],"description":"Error response following the RFC 7807 Problem Details standard","properties":{"type":{"type":"string","format":"uri","description":"A URI reference that identifies the problem type"},"title":{"type":"string","description":"A short, human-readable summary of the problem type"},"status":{"type":"integer","description":"The HTTP status code for this problem"},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem, including relevant identifiers to help with debugging"},"instance":{"type":"string","format":"uri-reference","description":"The specific API path that generated the error"},"request_id":{"type":"string","format":"uuid","description":"A unique identifier for the request, useful for tracing and support"}}}}},"paths":{"/locations":{"get":{"summary":"List of accessible locations","tags":["Locations"],"parameters":[{"name":"limit","description":"Limits how many records are returned in the response.","in":"query","required":false,"schema":{"type":"integer","default":1000,"maximum":1000,"minimum":1}},{"name":"cursor","in":"query","required":false,"description":"Cursor value from the previous response's pagination object used to fetch the next or previous page of results.","schema":{"type":"string"}}],"responses":{"200":{"description":"A flat list of accessible locations.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocationsResponse"}}}},"500":{"description":"Unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

***

## GET /locations/{id}

> Get location details

```json
{"openapi":"3.0.0","info":{"title":"Occuspace Customer API","version":"2.0.0"},"servers":[{"url":"https://api.occuspace.io/v2"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"LocationDetailResponse":{"type":"object","required":["data","pagination"],"properties":{"data":{"$ref":"#/components/schemas/LocationDetail"},"pagination":{"$ref":"#/components/schemas/Pagination"}}},"LocationDetail":{"type":"object","required":["location_id","name","status","parent_id","capacity","start_date"],"properties":{"location_id":{"type":"integer","description":"ID of the location.  Can be used on other endpoints for specific resources on the location in question."},"name":{"type":"string","description":"Name of the location."},"status":{"type":"string","enum":["active","inactive","setup","calibration","review"],"description":"Current status of this location."},"parent_id":{"type":"integer","nullable":true,"description":"ID of the parent location. Null if it is the root location."},"capacity":{"type":"integer","description":"Capacity of the location (includes the sum of all children locations if applicable)."},"start_date":{"type":"string","format":"date","nullable":true,"description":"Date string to indicate the earliest measured data.  Null if no data has been captured for this location."},"children_data":{"type":"array","description":"Details for each child location. Only present when include=children is passed in the request.","items":{"$ref":"#/components/schemas/LocationDetailChild"}}}},"LocationDetailChild":{"type":"object","description":"Location details for a child location","properties":{"location_id":{"type":"integer","description":"ID of the child location."},"name":{"type":"string","description":"Name of this child location."},"status":{"type":"string","enum":["active","inactive","setup","calibration","review"],"description":"Current status of this child location."},"parent_id":{"type":"integer","nullable":true,"description":"ID of this child's parent location."},"capacity":{"type":"integer","description":"Capacity of this child location."},"start_date":{"type":"string","format":"date","nullable":true,"description":"Date string to indicate the earliest measured data.  Null if no data has been captured for this location."}}},"Pagination":{"type":"object","required":["prev_cursor","next_cursor","has_more"],"properties":{"prev_cursor":{"type":"string","nullable":true},"next_cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}},"ErrorResponse":{"type":"object","required":["type","title","status","detail","instance","request_id"],"description":"Error response following the RFC 7807 Problem Details standard","properties":{"type":{"type":"string","format":"uri","description":"A URI reference that identifies the problem type"},"title":{"type":"string","description":"A short, human-readable summary of the problem type"},"status":{"type":"integer","description":"The HTTP status code for this problem"},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem, including relevant identifiers to help with debugging"},"instance":{"type":"string","format":"uri-reference","description":"The specific API path that generated the error"},"request_id":{"type":"string","format":"uuid","description":"A unique identifier for the request, useful for tracing and support"}}}}},"paths":{"/locations/{id}":{"get":{"summary":"Get location details","tags":["Locations"],"parameters":[{"name":"id","in":"path","required":true,"description":"The ID of the location.","schema":{"type":"integer"}},{"name":"include","in":"query","required":false,"description":"Pass \"children\" to include child locations of the current location in the response.","schema":{"type":"string","enum":["children"]}},{"name":"limit","in":"query","required":false,"description":"Maximum number of children to return per page when using include=children. Defaults to 1000 if not specified.","schema":{"type":"integer","default":1000}},{"name":"cursor","in":"query","required":false,"description":"Cursor value from the previous response's pagination object used to fetch the next or previous page of children when using include=children.","schema":{"type":"string"}}],"responses":{"200":{"description":"Location details found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocationDetailResponse"}}}},"404":{"description":"Location not found or not accessible with the provided credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

***

## GET /locations/{id}/now

> Get real-time occupancy data for a location

```json
{"openapi":"3.0.0","info":{"title":"Occuspace Customer API","version":"2.0.0"},"servers":[{"url":"https://api.occuspace.io/v2"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"LocationNowResponse":{"type":"object","required":["data","pagination"],"properties":{"data":{"$ref":"#/components/schemas/LocationNow"},"pagination":{"$ref":"#/components/schemas/Pagination"}}},"LocationNow":{"type":"object","required":["location_id","name","status","count","percentage","timestamp"],"description":"Current occupancy data for a location","properties":{"location_id":{"type":"integer","description":"ID of this location."},"name":{"type":"string","description":"Name of this location."},"status":{"type":"string","enum":["active","inactive","setup","calibration","review"],"description":"Current status of this location."},"count":{"type":"integer","description":"Current number of people estimated at this location."},"percentage":{"type":"number","format":"float","description":"Current count occupancy as a fraction of capacity."},"timestamp":{"type":"string","format":"date-time","description":"UTC timestamp of when the current count estimation."},"children_data":{"type":"array","description":"Only present when include=children is passed in the request.","items":{"$ref":"#/components/schemas/LocationNowChild"}}}},"LocationNowChild":{"type":"object","description":"Current occupancy data for a child location","properties":{"location_id":{"type":"integer","description":"ID of the child location."},"name":{"type":"string","description":"Name of this child location."},"status":{"type":"string","enum":["active","inactive","setup","review","calibration"],"description":"Current status of this child location."},"count":{"type":"integer","description":"Current number of people estimated at this child location."},"percentage":{"type":"number","format":"float","description":"Current count occupancy as a fraction of capacity."}}},"Pagination":{"type":"object","required":["prev_cursor","next_cursor","has_more"],"properties":{"prev_cursor":{"type":"string","nullable":true},"next_cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}},"ErrorResponse":{"type":"object","required":["type","title","status","detail","instance","request_id"],"description":"Error response following the RFC 7807 Problem Details standard","properties":{"type":{"type":"string","format":"uri","description":"A URI reference that identifies the problem type"},"title":{"type":"string","description":"A short, human-readable summary of the problem type"},"status":{"type":"integer","description":"The HTTP status code for this problem"},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem, including relevant identifiers to help with debugging"},"instance":{"type":"string","format":"uri-reference","description":"The specific API path that generated the error"},"request_id":{"type":"string","format":"uuid","description":"A unique identifier for the request, useful for tracing and support"}}}}},"paths":{"/locations/{id}/now":{"get":{"summary":"Get real-time occupancy data for a location","tags":["Locations"],"parameters":[{"name":"id","in":"path","required":true,"description":"The ID of the location.","schema":{"type":"integer"}},{"name":"include","in":"query","required":false,"description":"Pass \"children\" to include current occupancy for child locations in the response.","schema":{"type":"string","enum":["children"]}},{"name":"limit","in":"query","required":false,"description":"Maximum number of children to return per page when using include=children. Defaults to 1000 if not specified.","schema":{"type":"integer","default":1000}},{"name":"cursor","in":"query","required":false,"description":"Cursor value from the previous response's pagination object used to fetch the next page of children when using include=children.","schema":{"type":"string"}}],"responses":{"200":{"description":"Current real-time occupancy data for the location.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocationNowResponse"}}}},"404":{"description":"Location not found or not accessible with the provided credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.occuspace.io/api-reference/locations.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.