Locations API

Locations API Reference

Locations API Examples

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

Location Creation

Define the location parameters and store in /path/to/jsonfile:

{
   "display_name": "Macclesfield, Cheshire",
   "description": "Manufacturing site, North West England, Macclesfield, Cheshire",
   "latitude": 53.2546799,
   "longitude": -2.1213956,
   "attributes": {
       "director": "John Smith",
       "address": "Unit 6A, Synsation Park, Maccelsfield",
       "Facility Type": "Manufacture",
       "support_email": "support@macclesfield.com",
       "support_phone": "123 456 789"
    }
}

Create the location to POSTing to the locations resource:

curl -v -X POST \
    -H "@$BEARER_TOKEN_FILE" \
    -H "Content-type: application/json" \
    -d "@/path/to/jsonfile" \
    https://app.rkvst.io/archivist/v2/locations

The response is:

{
    "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,
    "attributes": {
        "director": "John Smith",
        "address": "Bridgewater, Somerset",
        "Facility Type": "Manufacture",
        "support_email": "support@macclesfield.com",
        "support_phone": "123 456 789"
    }
}

Location Retrieval

Fetch All Locations

To fetch all locations, simply GET the locations resource:

curl -v -X GET \
     -H "@$BEARER_TOKEN_FILE" \
     https://app.rkvst.io/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" \
     https://app.rkvst.io/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" \
    https://app.rkvst.io/archivist/v2/locations?display_name=Macclesfield%2C%20Cheshire

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"
            }
        }
    ]
}

Locations OpenAPI Docs

get  /archivist/v2/locations

List locations

Description: Returns a paginated list of locations

null
Response Parameter Type Description
locations array Describes a location for asset resources
next_page_token string Token to retrieve the next page of results or empty if there are none.
Responses Description
200A successful response.
401Returned when the user is not authenticated to the system.
403Returned when the user is not authorized to read the location.
defaultAn unexpected error response.

post  /archivist/v2/locations

Create a location

Description: This request creates a new location. A name and a latitude and longitude must be provided. The display_name is the friendly name. The latitude and longitude must be entered in Degrees Decimal format See Change of units and format. The attributes field is a flat map of { "key": "value" }. The keys and values must be strings.

{
  "attributes": {
    "Facility Type": "Manufacture",
    "address": "Bridgewater, Somerset",
    "director": "John Smith",
    "support_email": "support@macclesfield.com",
    "support_phone": "123 456 789"
  },
  "description": "Manufacturing site, North West England, Macclesfield, Cheshire",
  "display_name": "Macclesfield, Cheshire",
  "latitude": "53.2546799",
  "longitude": "-2.1213956,14.54"
}
Parameter Type Description
attributes object key value mapping of location properties
description string Free text description of the location
display_name string Customer friendly name for the asset.
latitude number Latitude in decimal degrees format.
longitude number longitude in decimal degrees format.

{
  "attributes": {
    "Facility Type": "Manufacture",
    "address": "Bridgewater, Somerset",
    "director": "John Smith",
    "support_email": "support@macclesfield.com",
    "support_phone": "123 456 789"
  },
  "description": "Manufacturing site, North West England, Macclesfield, Cheshire",
  "display_name": "Macclesfield, Cheshire",
  "identity": "locations/08838336-c357-460d-902a-3aba9528dd22",
  "latitude": "53.2546799",
  "longitude": "-2.1213956,14.54"
}
Response Parameter Type Description
attributes object key value mapping of asset properties
description string Free text description of the location
display_name string Customer friendly name for the location.
identity string Unique identification for the location, Relative Resource Name
latitude number Latitude in decimal degrees
longitude number Longitude in decimal degrees
owner string wallet address of the location owner
tenant string Tenent id
Responses Description
200A successful response.
401Returned when the user is not authenticated to the system.
403Returned when the user is not authorized to create a location.
defaultAn unexpected error response.

delete  /archivist/v2/locations/{uuid}

Delete a location

Description: Delete the identified location

Responses Description
200A successful response.
401Returned when the user is not authenticated to the system.
403Returned when the user is not authorized to delete the location.
404Returned when the identified location does not exist.
defaultAn unexpected error response.

get  /archivist/v2/locations/{uuid}

Get a location

Description: Returns the identified location

{
  "attributes": {
    "Facility Type": "Manufacture",
    "address": "Bridgewater, Somerset",
    "director": "John Smith",
    "support_email": "support@macclesfield.com",
    "support_phone": "123 456 789"
  },
  "description": "Manufacturing site, North West England, Macclesfield, Cheshire",
  "display_name": "Macclesfield, Cheshire",
  "identity": "locations/08838336-c357-460d-902a-3aba9528dd22",
  "latitude": "53.2546799",
  "longitude": "-2.1213956,14.54"
}
Response Parameter Type Description
attributes object key value mapping of asset properties
description string Free text description of the location
display_name string Customer friendly name for the location.
identity string Unique identification for the location, Relative Resource Name
latitude number Latitude in decimal degrees
longitude number Longitude in decimal degrees
owner string wallet address of the location owner
tenant string Tenent id
Responses Description
200A successful response.
401Returned when the user is not authenticated to the system.
403Returned when the user is not authorized to read the location.
404Returned when the identified location does not exist.
defaultAn unexpected error response.

patch  /archivist/v2/locations/{uuid}

Update a location's details

Description: Perform a full or partial update of the identified location

{
  "attributes": {
    "Facility Type": "Manufacture",
    "address": "Bridgewater, Somerset",
    "director": "John Smith",
    "support_email": "support@macclesfield.com",
    "support_phone": "123 456 789"
  },
  "description": "Manufacturing site, North West England, Macclesfield, Cheshire",
  "display_name": "Macclesfield, Cheshire",
  "identity": "locations/08838336-c357-460d-902a-3aba9528dd22",
  "latitude": "53.2546799",
  "longitude": "-2.1213956,14.54"
}
Parameter Type Description
attributes object key value mapping of asset properties
description string Free text description of the location
display_name string Customer friendly name for the location.
identity string Unique identification for the location, Relative Resource Name
latitude number Latitude in decimal degrees
longitude number Longitude in decimal degrees
owner string wallet address of the location owner
tenant string Tenent id

{
  "attributes": {
    "Facility Type": "Manufacture",
    "address": "Bridgewater, Somerset",
    "director": "John Smith",
    "support_email": "support@macclesfield.com",
    "support_phone": "123 456 789"
  },
  "description": "Manufacturing site, North West England, Macclesfield, Cheshire",
  "display_name": "Macclesfield, Cheshire",
  "identity": "locations/08838336-c357-460d-902a-3aba9528dd22",
  "latitude": "53.2546799",
  "longitude": "-2.1213956,14.54"
}
Response Parameter Type Description
attributes object key value mapping of asset properties
description string Free text description of the location
display_name string Customer friendly name for the location.
identity string Unique identification for the location, Relative Resource Name
latitude number Latitude in decimal degrees
longitude number Longitude in decimal degrees
owner string wallet address of the location owner
tenant string Tenent id
Responses Description
200A successful response.
401Returned when the user is not authenticated to the system.
403Returned when the user is not authorized to update the location.
404Returned when the identified location does not exist.
defaultAn unexpected error response.

get  /archivist/v2/locations/{uuid}/permissions

Get location permissions

Description: Get location permissions for identified location

null
Response Parameter Type Description
location_identity string
permissions
Responses Description
200A successful response.
401Returned when the user is not authenticated to the system.
403Returned when the user is not authorized to list permissions for the location.
404Returned when the identified location does not exist.
defaultAn unexpected error response.

patch  /archivist/v2/locations/{uuid}/permissions

Patch location permissions

Description: Patch location permissions for identified location

null
Parameter Type Description
subject_identities array list of subject identities this location is shared with

null
Response Parameter Type Description
location_identity string
permissions
Responses Description
200A successful response.
401Returned when the user is not authenticated to the system.
403Returned when the user is not authorized to access permissions for the location.
404Returned when the identified location does not exist.
defaultAn unexpected error response.

Edit this page on GitHub