List all locations

GET api/locations

List all locations.

Request syntax

get api/locations

Request parameters

The request accepts the following data in JSON format.

Parameter	Type	Description	Required	Default value
`page`	Integer	The page number to retrieve.	No	`1`
`page_size`	Integer	The number of results to return for each page.	No	`1000`

Response syntax

{
    "page": integer,
    "page_size": integer,
    "pages_total": integer,
    "items_total": integer,
    "locations": [
        {
            "location_id": integer,
            "name": "string",
            "template_name": "string",
            "updated_at": "timestamp",
            "nodes": []
        },
        {
            "location_id": integer,
            "name": "string",
            "template_name": "string",
            "addressline1": "string",
            "addressline2": "string",
            "city": "string",
            "state": "string",
            "zipcode": "string",
            "country": "string",
            "updated_at": "timestamp",
            "nodes": [
                {
                    "node_id": integer,
                    "hostname": "string",
                    "keepalive": "string",
                    "keepalive_timestamp": integer,
                    "last_online": "string",
                    "hardware_type": "string",
                    "updated_at": "timestamp"
                },
                {
                    "node_id": integer,
                    "hostname": "string",
                    "keepalive": "string",
                    "keepalive_timestamp": integer,
                    "last_online": "string",
                    "hardware_type": "string",
                    "updated_at": "timestamp"
                }
            ]
        }
    ]
}

Response parameters

If the action is successful, an HTTP 200 response is returned. The following data is returned in JSON format.

Field	Type	Description
`page`	Integer	The page number for the response.
`page_size`	Integer	The number of locations returned on the page. The maximum number of locations that can be returned per page is `1000`.
`pages_total`	Integer	The total number of pages required to display all locations.
`items_total`	Integer	The total number of locations.
`locations`	Array of objects	The properties associated with the locations.

Errors

The following are errors returned by this API. For a complete list of common errors, see Common errors.

Code	Message	Cause
-	-	-

Examples

Example: List all locations.

This example lists all locations.

ruby api.rb <customer_code> get api/locations

Response

{
    "page": 1,
    "page_size": 2,
    "pages_total": 1,
    "items_total": 2,
    "locations": [
        {
            "location_id": 8,
            "name": "Unassigned",
            "template_name": "unassigned",
            "updated_at": "2023-09-27T18:09:40.367Z",
            "nodes": []
        },
        {
            "location_id": 12722,
            "name": "Location 0019",
            "template_name": "location_0019",
            "addressline1": "123 Please Update Me",
            "addressline2": null,
            "city": "Austin",
            "state": "TX",
            "zipcode": "11111",
            "country": "US",
            "updated_at": "2024-04-15T19:03:44.031Z",
            "nodes": [
                {
                    "node_id": 71901,
                    "hostname": "sit0000red0",
                    "keepalive": "unknown",
                    "keepalive_timestamp": 1726249079,
                    "last_online": "unknown",
                    "hardware_type": "test hardware",
                    "updated_at": "2024-04-15T19:03:23.753Z"
                },
                {
                    "node_id": 71902,
                    "hostname": "sit0000red1",
                    "keepalive": "unknown",
                    "keepalive_timestamp": 1726249079,
                    "last_online": "unknown",
                    "hardware_type": "test hardware",
                    "updated_at": "2024-04-15T19:03:44.016Z"
                }
            ]
        }
    ]
}