List locations

POST

/v1alpha2/inventory/locations

Request Body

Media typeapplication/json

object

pageSize

integer format: int32

page

integer format: int32

filters

object

onlyConflicts

Only physical locations whose versions diverge: more than one distinct content checksum among the canonical and partner versions.

boolean

onlyOwn

Only physical locations claimed by the caller’s own scope: an organization-scoped caller matches by claiming organization, a project-scoped caller matches by claiming project. The scope is derived server-side from the caller’s namespace, not client-supplied.

boolean

externalId

Case-insensitive substring match on the physical location’s external_id.

string

name

Case-insensitive substring match on the physical location’s metadata.name.

string

sort

LocationSort orders rows by a display-summary field (the canonical-first values), external_id ascending by default.

object

field

• LOCATION_SORT_FIELD_UNSPECIFIED: Defaults to sorting by external_id, ascending.

string

default: LOCATION_SORT_FIELD_UNSPECIFIED

Allowed values: LOCATION_SORT_FIELD_UNSPECIFIED LOCATION_SORT_FIELD_STORE_SUBCHAIN LOCATION_SORT_FIELD_MERCHANT LOCATION_SORT_FIELD_CITY

direction

string

default: SORT_DIRECTION_UNSPECIFIED

Allowed values: SORT_DIRECTION_UNSPECIFIED SORT_DIRECTION_ASC SORT_DIRECTION_DESC

Responses

200

A successful response.

Media typeapplication/json

object

locations

Array<object>

LocationListItem is one physical location: display values plus every stored version, so a client can expand a row without a second call.

object

resource

The partner version, falling back to the canonical.

object

summary

Summary is the short list-view projection of one stored Location version — a canonical record or one partner’s latest copy.

object

ids

The ids of this version’s Location record.

object

location

string

organization

string

project

string

externalId

Client defined unique id, shared by every version of the same physical location.

string

name

Display name of the location.

string

status

The operational status of the location.

string

default: STATUS_UNSPECIFIED

Allowed values: STATUS_UNSPECIFIED STATUS_INACTIVE STATUS_ACTIVE

storeChain

Retail chain brand name, e.g. “EDEKA”.

string

storeSubchain

Distribution line / sub-chain name, e.g. “EDEKA Nordbayern”.

string

merchant

Store owner / contract holder name.

string

city

City of the location’s address.

string

country

Country of the location’s address.

string

address

The location’s full address.

object

country

string

city

string

street

string

number

string

zipCode

string

region

string

state

string

source

LocationSource tells which collection a version comes from.

• LOCATION_SOURCE_CANONICAL: The tenant-wide consensus record.
• LOCATION_SOURCE_LATEST: One partner’s latest copy.

string

default: LOCATION_SOURCE_UNSPECIFIED

Allowed values: LOCATION_SOURCE_UNSPECIFIED LOCATION_SOURCE_CANONICAL LOCATION_SOURCE_LATEST

organization

The partner’s organization name; empty for the canonical version.

string

versions

Every stored version of this physical location, canonical first.

Array<object>

LocationVersion is one stored version of a physical location.

object

summary

Summary is the short list-view projection of one stored Location version — a canonical record or one partner’s latest copy.

object

ids

The ids of this version’s Location record.

object

location

string

organization

string

project

string

externalId

Client defined unique id, shared by every version of the same physical location.

string

name

Display name of the location.

string

status

The operational status of the location.

string

default: STATUS_UNSPECIFIED

Allowed values: STATUS_UNSPECIFIED STATUS_INACTIVE STATUS_ACTIVE

storeChain

Retail chain brand name, e.g. “EDEKA”.

string

storeSubchain

Distribution line / sub-chain name, e.g. “EDEKA Nordbayern”.

string

merchant

Store owner / contract holder name.

string

city

City of the location’s address.

string

country

Country of the location’s address.

string

address

The location’s full address.

object

country

string

city

string

street

string

number

string

zipCode

string

region

string

state

string

source

LocationSource tells which collection a version comes from.

• LOCATION_SOURCE_CANONICAL: The tenant-wide consensus record.
• LOCATION_SOURCE_LATEST: One partner’s latest copy.

string

default: LOCATION_SOURCE_UNSPECIFIED

Allowed values: LOCATION_SOURCE_UNSPECIFIED LOCATION_SOURCE_CANONICAL LOCATION_SOURCE_LATEST

organization

The partner’s organization name; empty for the canonical version.

string

hasConflict

True when the versions carry more than one distinct content checksum.

boolean

deviceCount

How many devices are deployed at this physical location, counted across every version (the canonical and every partner’s) regardless of which project claims them — the count pair of LocationsGetResponse.devices.

integer format: int32

totalCount

integer format: int32

totalPages

integer format: int32

currentPage

integer format: int32

Example

{
  "locations": [
    {
      "resource": {
        "summary": {
          "status": "STATUS_UNSPECIFIED"
        },
        "source": "LOCATION_SOURCE_UNSPECIFIED"
      },
      "versions": [
        {
          "summary": {
            "status": "STATUS_UNSPECIFIED"
          },
          "source": "LOCATION_SOURCE_UNSPECIFIED"
        }
      ]
    }
  ]
}