Location Retrieval

Create the bearer_token and store in a file in a secure local directory with 0600 permissions.

See API Request Authorization and Authentication.

Note

The following example shows use of the API over curl in a bash terminal. The concepts are fully portable to any other REST client (eg PostMan or python requests)

Set the URL (for example):

$ export URL=https://synsation.1234-5678.nodes.archivist.jitsuin.io

Fetch all locations

To fetch all locations, simply GET the locations resource:

$ curl -v -X GET \
     -H "@$BEARER_TOKEN_FILE" \
     $URL/archivist/v2/locations

Fetch specific location by identity

If you know the unique identity of the location record, simply GET the resource:

$ curl -v -X GET \
     -H "@$BEARER_TOKEN_FILE" \
     $URL/archivist/v2/locations/08838336-c357-460d-902a-3aba9528dd22

Fetch location by name

To fetch all locations with a specific name, GET the assets resource and filter on display_name:

$ curl -v -X GET \
    -H "@$BEARER_TOKEN_FILE" \
    $URL/archivist/v2/locations?display_name=Macclesfield%2C%20Cheshire

Note

It is advisable to implement a unique naming scheme for location names, but this is not enforced by the system. If multiple locations exist with the same name they will all be returned, and the client will need to differentiate based on other attributes.

Each of these calls returns a list of matching asset records in the form:

{
    "locations": [
        {
            "identity": "locations/08838336-c357-460d-902a-3aba9528dd22",
            "display_name": "Macclesfield, Cheshire",
            "description": "Manufacturing site, North West England, Macclesfield, Cheshire",
            "latitude": "53.2546799",
            "longitude": "-2.1213956,14.54",
            "attributes": {
                "director": "John Smith",
                "address": "Bridgewater, Somerset",
                "Facility Type": "Manufacture",
                "support_email": "support@macclesfield.com",
                "support_phone": "123 456 789"
            }
        }
    ]
}

Note

The number of records returned has a maximum limit. If this limit is too small then one must use API Request Paging.

Note

The total number of assets that exist is returned in the response header field ‘x-total-count’ if the ‘x-request-total-count’ header on the request is set to ‘true’. The curl option ‘-i’ will emit this to stdout.

Note

A full API reference is available in Swagger GET API