# 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"}}}}}}}}}
```