Location

Locations are physical sites, facilities, or addresses where supply chain activities take place in TrackVision. They can also model sub-locations (e.g. production lines, loading docks, storage bins) by using the GLN Extension attribute.

The `location` Object

Locations store comprehensive information about physical places including addresses, contact details, geographical coordinates, and organizational relationships.

Field Name	Type	Description
`id`	string	Primary key for the location. Auto set if using GS1 IDs.
`user_created`	object	User who created the location. Read-only. Links to directus_users.
`date_created`	datetime	Timestamp in ISO 8601 when the location was created. Read-only.
`user_updated`	object	User who last updated the location. Read-only. Links to directus_users.
`date_updated`	datetime	Timestamp in ISO 8601 when the location was last updated. Read-only.
`location_name`	string	The name or title of the location.
`third_party_location`	boolean	Indicates if this is a third-party managed location.
`timezone`	string	Timezone identifier for the location (e.g., "UTC+1").
`gln`	string	Global Location Number (GLN) - the globally unique identifier for the location.
`gln_extension`	string	GLN extension for sub-locations or specific areas within the main location.
`address`	string	Street address of the location.
`city`	string	City where the location is situated.
`state`	string	State, province, or region of the location.
`county`	string	County of the location.
`postal_code`	string	Postal or ZIP code for the location.
`country_code`	object	ISO country code reference for the location. Links to ref_country.
`primary_contact_telephone`	string	Primary telephone number for the location.
`primary_contact_type`	string	Type of primary contact (e.g., "Manager", "Security", "Reception").
`primary_contact_email`	string	Primary email address for the location.
`primary_contact_title`	string	Job title of the primary contact person.
`digital_link`	string	GS1 Digital Link URL for the location. Auto generated if using GS1 IDs.
`custom_id`	string	Custom internal identifier for the location. Hidden by default on UI.
`location_redirection_url`	string	URL where the location should redirect when scanned.
`primary_image`	object	Primary image file for the location. Links to directus_files.
`location_role`	object	JSON array defining the roles/functions of this location (e.g., FARM, MANUFACTURING_PLANT, WAREHOUSE_AND_OR_DEPOT, STORAGE_LOCATION, STORE).
`parent_location`	object	Reference to parent location in hierarchical structure. Links to location.
`owning_organisation`	object	Organisation that owns this location. Links to organisation.
`related_organisation`	object	Organisation related to or operating at this location. Links to organisation.
`account`	object	Account associated with this location. (Multi-tenant installations only)
`latitude`	number	Geographic latitude coordinate.
`longitude`	number	Geographic longitude coordinate.
`map`	object	JSON object containing map-related data or configurations.
`location_redirection_rule`	object	Flow rule for advanced redirection logic. Links to directus_flows.
`use_gs1_identifiers`	boolean	Whether GS1 identifiers are used for this location.
`translations`	array of objects	Translations for multi-lingual location content.
`certifications`	array of objects	Certifications associated with this location.

Sub-Objects

User Object (`user_created`, `user_updated`)

See Users for the full schema.

Account Object (`account`)

See Account for the full schema.

File Object (`primary_image`)

See Files for the full schema.

Country Object (`country_code`)

See Country for the full schema.

Location Object (`parent_location`)

See Location for the full schema.

Organisation Object (`owning_organisation`, `related_organisation`)

See Organisation for the full schema.

Location Translation Object (`translations`)

Field	Type	Description
`id`	integer	Unique identifier of the translation record.
`languages_code`	string	Language code for this translation (e.g., "en-US").
`location_description`	string	Translated location description.
`location_content`	string	Translated location content.

List Locations

List existing locations.

REST
GraphQL

GET /items/location

query {
  location {
    id
    location_name
    gln
    address
    city
    state
    country_code {
      code
      name
    }
    custom_id
    location_role
    latitude
    longitude
  }
}

Query Parameters

Supports all global query parameters.

Returns

An array of up to limit location objects. If no items are available, data will be an empty array.

Retrieve a Location

Retrieve a specific location by ID.

REST
GraphQL

GET /items/location/:id

query {
  location_by_id(id: "location_id") {
    id
    location_name
    third_party_location
    timezone
    gln
    gln_extension
    address
    city
    state
    postal_code
    country_code {
      code
      name
    }
    primary_contact_telephone
    primary_contact_type
    primary_contact_email
    primary_contact_title
    digital_link
    custom_id
    location_redirection_url
    primary_image {
      id
      filename_download
    }
    location_role
    parent_location {
      id
      location_name
    }
    owning_organisation {
      id
      name
    }
    related_organisation {
      id
      name
    }
    account {
      id
      name
    }
    latitude
    longitude
    map
    user_created {
      id
      first_name
      last_name
    }
    date_created
    user_updated {
      id
      first_name
      last_name
    }
    date_updated
  }
}

Returns

Returns a location object if a valid primary key was provided.

Create a Location

Create a new location.

REST
GraphQL

POST /items/location

{
  "location_name": "Jamshedpur Plant",
  "third_party_location": false,
  "gln": "0053893100012",
  "address": "Bara PO Agrico",
  "city": "Jamshedpur",
  "state": "Jharkhand",
  "postal_code": "831009",
  "country_code": "IN",
  "primary_contact_telephone": "+91(657)2210293",
  "digital_link": "https://mybrand.tvai.me/414/0053893100012",
  "custom_id": "IN48",
  "location_redirection_url": "https://www.company.com/",
  "location_role": ["MANUFACTURING_PLANT"],
  "owning_organisation": "/417/0053893000008",
  "latitude": 22.806756,
  "longitude": 86.230829,
  "map": {
    "coordinates": [86.230829, 22.806756],
    "type": "Point"
  }
}

mutation {
  create_location_item(data: {
    location_name: "Jamshedpur Plant"
    third_party_location: false
    gln: "0053893100012"
    address: "Bara PO Agrico"
    city: "Jamshedpur"
    state: "Jharkhand"
    postal_code: "831009"
    country_code: "IN"
    primary_contact_telephone: "+91(657)2210293"
    digital_link: "https://food.tvai.me/414/0053893100012"
    custom_id: "IN48"
    location_redirection_url: "https://www.company.com/"
    location_role: ["MANUFACTURING_PLANT"]
    owning_organisation: "/417/0053893000008"
    latitude: 22.806756
    longitude: 86.230829
    map: {
      coordinates: [86.230829, 22.806756]
      type: "Point"
    }
  }) {
    id
    location_name
    gln
    address
    city
  }
}

Query Parameters

Supports all global query parameters.

Request Body

A partial location object.

Returns

Returns the location object for the created location.

Update a Location

Update an existing location.

REST
GraphQL

PATCH /items/location/:id

{
  "location_name": "Jamshedpur Plant - Expanded",
  "primary_contact_telephone": "+91(657)2210294",
  "location_redirection_url": "https://www.company.com/locations/india/",
  "location_role": ["MANUFACTURING_PLANT", "WAREHOUSE_AND_OR_DEPOT"]
}

mutation {
  update_location_item(id: "/414/0053893100012", data: {
    location_name: "Jamshedpur Plant - Expanded"
    primary_contact_telephone: "+91(657)2210294"
    location_redirection_url: "https://www.company.com/locations/india/"
    location_role: ["MANUFACTURING_PLANT", "WAREHOUSE_AND_OR_DEPOT"]
  }) {
    id
    location_name
    primary_contact_telephone
    location_redirection_url
    location_role
  }
}

Query Parameters

Supports all global query parameters.

Request Body

A partial location object.

Returns

Returns the location object for the updated location.

Delete a Location

Delete an existing location.

REST
GraphQL

DELETE /items/location/:id

mutation {
  delete_location_item(id: "location_id") {
    id
  }
}

Returns

Empty body.

The location Object​

Sub-Objects​

User Object (user_created, user_updated)​

Account Object (account)​

File Object (primary_image)​

Country Object (country_code)​

Location Object (parent_location)​

Organisation Object (owning_organisation, related_organisation)​

Location Translation Object (translations)​

List Locations​

Query Parameters​

Returns​

Retrieve a Location​

Returns​

Create a Location​

Query Parameters​

Request Body​

Returns​

Update a Location​

Query Parameters​

Request Body​

Returns​

Delete a Location​

Returns​

The `location` Object

Sub-Objects

User Object (`user_created`, `user_updated`)

Account Object (`account`)

File Object (`primary_image`)

Country Object (`country_code`)

Location Object (`parent_location`)

Organisation Object (`owning_organisation`, `related_organisation`)

Location Translation Object (`translations`)

List Locations

Query Parameters

Returns

Retrieve a Location

Returns

Create a Location

Query Parameters

Request Body

Returns

Update a Location

Query Parameters

Request Body

Returns

Delete a Location

Returns