Skip to content
Verve Retail Media

List locations

POST
/v1alpha2/inventory/locations

Request Body

Section titled “Request Body”
Media typeapplication/json
object
pageSize
integer format: int32
Example
50
page
integer format: int32
Example
1
filters
object
onlyConflicts

Only physical locations whose versions have diverged: the canonical record and at least one partner copy hold different values.

boolean
onlyOwn

Only physical locations the caller owns. Ownership is resolved server-side and is not a value the client sets.

boolean
externalId

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

string
name

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

string
modifiedSince

Only physical locations whose canonical record has a metadata.lastUpdatedAt strictly after this instant, for polling what has changed since the last pass. RFC 3339.

The canonical record is what this compares against: an edit to a partner version that leaves the agreed values unchanged does not bring the location back. Pair it with a LOCATION_SORT_FIELD_FIRST_CREATED_AT sort, so page boundaries hold while you walk the changed set.

string format: date-time
sort

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

object
field
  • LOCATION_SORT_FIELD_UNSPECIFIED: Defaults to sorting by externalId, ascending.
  • LOCATION_SORT_FIELD_FIRST_CREATED_AT: metadata.firstCreatedAt of the canonical record. Fixed when the location is first registered, so a walk ordered by it is stable against concurrent edits in a way one ordered by a mutable field is not.
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 LOCATION_SORT_FIELD_FIRST_CREATED_AT
direction
string
default: SORT_DIRECTION_UNSPECIFIED
Allowed values: SORT_DIRECTION_UNSPECIFIED SORT_DIRECTION_ASC SORT_DIRECTION_DESC

Responses

Section titled “ Responses ”

200

Section titled “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

ISO 3166-1 alpha-2 country code, e.g. “DE” — not the country’s name.

string
city
string
street
string
number
string
zipCode
string
region
string
state
string
source

LocationSource tells which kind of version this is.

  • LOCATION_SOURCE_CANONICAL: The canonical record — the agreement across all partners.
  • 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

ISO 3166-1 alpha-2 country code, e.g. “DE” — not the country’s name.

string
city
string
street
string
number
string
zipCode
string
region
string
state
string
source

LocationSource tells which kind of version this is.

  • LOCATION_SOURCE_CANONICAL: The canonical record — the agreement across all partners.
  • 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 have diverged: they hold different values.

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
activeDeviceCount

How many of those devices are ACTIVE — the same set as deviceCount, narrowed to devices whose status is STATUS_ACTIVE. Zero means deleting the location breaks no live device.

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"
        }
      ]
    }
  ],
  "totalCount": 3,
  "totalPages": 1,
  "currentPage": 1
}