DataTrails

Locations API

Locations API Reference

Note: This page is primarily intended for developers who will be writing applications that will use DataTrails for provenance. If you are looking for a simple way to test our API you might prefer our Postman collection, the YAML runner or the Developers section of the web UI.

Additional YAML examples can be found in the articles in the Overview section.

Note: See DataTrails Administration for additional information on creating and using locations with DataTrails.

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 "@$HOME/.datatrails/bearer-token.txt" \
    -H "Content-type: application/json" \
    -d "@/path/to/jsonfile" \
    https://app.datatrails.ai/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 "@$HOME/.datatrails/bearer-token.txt" \
     https://app.datatrails.ai/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 "@$HOME/.datatrails/bearer-token.txt" \
     https://app.datatrails.ai/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 "@$HOME/.datatrails/bearer-token.txt" \
    "https://app.datatrails.ai/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

API to manage locations.

get  /archivist/v2/locations

List locations

Description: Returns a paginated list of locations

{
  "locations": [
    {
      "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
    },
    {
      "attributes": {
        "Facility Type": "Distribution",
        "address": "Newtown",
        "director": "June Smith",
        "support_email": "support@example.com",
        "support_phone": "321 654 987"
      },
      "description": "Distribution Centre, Wales, Cardiff, Glamorganshire",
      "display_name": "Cardiff, Glamorganshire",
      "identity": "locations/19749457-d468-572c-6e3b-3acb0417ec13",
      "latitude": 51.481583,
      "longitude": -3.17909
    }
  ],
  "next_page_token": "eyJvcmlnX3JlcSI6eyJwYWdlX3NpemUiOjJ9LCJza2lwIjoyfQ=="
}
Response ParameterTypeDescription
locationsarrayDescribes a location for asset resources
next_page_tokenstringToken to retrieve the next page of results or empty if there are none.
ResponsesDescription
200A successful response.
401Returned when the user is not authenticated to the system.
403Returned when the user is not authorized to read the location.
429Returned when a user exceeds their subscription’s rate limit for requests.

post  /archivist/v2/locations

Create a location

Description: Create a new 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",
  "latitude": 53.2546799,
  "longitude": -2.1213956
}
ParameterTypeDescription
attributesobjectkey value mapping of location properties
descriptionstringFree text description of the location
display_namestringCustomer friendly name for the location.
latitudenumberLatitude in decimal degrees format.
longitudenumberlongitude 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
}
Response ParameterTypeDescription
attributesobjectkey value mapping of asset properties
descriptionstringFree text description of the location
display_namestringCustomer friendly name for the location.
identitystringUnique identification for the location, Relative Resource Name
latitudenumberLatitude in decimal degrees
longitudenumberLongitude in decimal degrees
ownerstringwallet address of the location owner
tenantstringTenent id
ResponsesDescription
200A successful response.
401Returned when the user is not authenticated to the system.
402Returned when the user’s quota of locations policies has been reached.
403Returned when the user is not authorized to create a location.
429Returned when a user exceeds their subscription’s rate limit for requests.

delete  /archivist/v2/locations/{uuid}

Delete a location

Description: Delete the identified location

ResponsesDescription
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.
429Returned when a user exceeds their subscription’s rate limit for requests.

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
}
Response ParameterTypeDescription
attributesobjectkey value mapping of asset properties
descriptionstringFree text description of the location
display_namestringCustomer friendly name for the location.
identitystringUnique identification for the location, Relative Resource Name
latitudenumberLatitude in decimal degrees
longitudenumberLongitude in decimal degrees
ownerstringwallet address of the location owner
tenantstringTenent id
ResponsesDescription
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.
429Returned when a user exceeds their subscription’s rate limit for requests.

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
}
Response ParameterTypeDescription
attributesobjectkey value mapping of asset properties
descriptionstringFree text description of the location
display_namestringCustomer friendly name for the location.
identitystringUnique identification for the location, Relative Resource Name
latitudenumberLatitude in decimal degrees
longitudenumberLongitude in decimal degrees
ownerstringwallet address of the location owner
tenantstringTenent id
ResponsesDescription
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.
429Returned when a user exceeds their subscription’s rate limit for requests.

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

Get location permissions

Description: Get location permissions for identified location

{
  "location_identity": "locations/08838336-c357-460d-902a-3aba9528dd22",
  "permissions": {
    "subject_identities": [
      "bob@example.com",
      "orgb"
    ]
  }
}
Response ParameterTypeDescription
location_identitystringThe location identity in the form: locations/{uuid}
permissionsSubject identities this location is shared with
ResponsesDescription
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.
429Returned when a user exceeds their subscription’s rate limit for requests.

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

Patch location permissions

Description: Patch location permissions for identified location

{
  "location_identity": "locations/08838336-c357-460d-902a-3aba9528dd22",
  "permissions": {
    "subject_identities": [
      "bob@example.com",
      "orgb"
    ]
  }
}
Response ParameterTypeDescription
location_identitystringThe location identity in the form: locations/{uuid}
permissionsSubject identities this location is shared with
ResponsesDescription
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.
429Returned when a user exceeds their subscription’s rate limit for requests.

← Quickstart: SCITT Statements (Preview)
Public Assets API →