List Locations

curl -X GET "https://connect.wholechain.com/Integration/Locations?PageNumber=1&PageSize=10" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: example_string"

import requests
import json

url = "https://connect.wholechain.com/Integration/Locations?PageNumber=1&PageSize=10"
headers = {
  "Content-Type": "application/json",
  "X-API-KEY": "example_string"
}

response = requests.get(url, headers=headers)
print(response.json())

const response = await fetch("https://connect.wholechain.com/Integration/Locations?PageNumber=1&PageSize=10", {
  method: "GET",
  headers: {
  "Content-Type": "application/json",
  "X-API-KEY": "example_string"
}
});

const data = await response.json();
console.log(data);

package main

import (
    "fmt"
    "net/http"
)

func main() {

    req, err := http.NewRequest("GET", "https://connect.wholechain.com/Integration/Locations?PageNumber=1&PageSize=10", nil)
    if err != nil {
        panic(err)
    }

    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("X-API-KEY", "example_string")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    fmt.Println("Response Status:", resp.Status)
}

require 'net/http'
require 'json'

uri = URI('https://connect.wholechain.com/Integration/Locations?PageNumber=1&PageSize=10')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri)
request['Content-Type'] = 'application/json'
request['X-API-KEY'] = 'example_string'

response = http.request(request)
puts response.body

{
  "totalPages": 1,
  "pageNumber": 1,
  "pageSize": 1,
  "totalItems": 1,
  "results": [
    {
      "id": "shipFrom_000",
      "urn": "urn:gdst:wholechain.com:location:loc:oceanagroupltd.supplierlocation",
      "details": {
        "tradePartner": {
          "id": "supplier_123",
          "urn": "urn:gdst:wholechain.com:party:suppliertp.0",
          "name": "SupplierTP",
          "pgln": "",
          "connectionType": "OTHER",
          "duns": "123456789"
        },
        "name": "Supplier Location",
        "gln": "9506000140445",
        "dunsPlus4": null,
        "externalIdentifier": "shipFrom_000",
        "extension": "SomeExtension",
        "captainsName": null,
        "address": {
          "city": "City Name",
          "state": "State Name",
          "country": "Country Name",
          "addressLine1": "",
          "addressLine2": "",
          "postalCode": "12345",
          "geoCoordinates": {
            "latitude": 12.345678,
            "longitude": 98.765432
          },
          "displayAddress": "City Name, State Name, Country Name"
        },
        "contact": null,
        "vessel": null,
        "foodFacilityRegistrationNumber": null,
        "locationType": null
      },
      "updateIfExists": false
    }
  ],
  "hasNextPage": false,
  "hasPreviousPage": false
}

GET

/Integration/Locations

GET

Base URLstring

Target server for requests. Edit to use your own host.

query

PageNumberinteger

Default 1, minimum 1.

Min: 1

query

PageSizeinteger

Default 20, minimum 1.

Min: 1

header

X-API-KEYstring

Required

API key used to authenticate the request.

Request Preview

Response

Response will appear here after sending the request

Responses

totalPagesinteger

Required

pageNumberinteger

Required

pageSizeinteger

Required

totalItemsinteger

Required

resultsarray

Required

hasNextPageboolean

Required

hasPreviousPageboolean

Required

Introduction

The Get Locations API allows you to retrieve a list of locations available within your Wholechain account.

The API key is required. Pagination parameters are optional.

If PageNumber and PageSize are omitted, the first page of 20 locations is returned. Use PageNumber, PageSize and hasNextPage to read all locations.

Request Headers

Header	Required	Description	Example Value
`X-API-KEY`	Yes	API key used to authenticate the request.	`YOUR_API_KEY`
`accept`	No	Response content type.	`text/plain`

Query Parameters

Parameter	Data Type	Required	Description	Example
`PageNumber`	INTEGER	No	Page number to return. Default 1, minimum 1.	`1`
`PageSize`	INTEGER	No	Number of locations per page. Default 20, minimum 1.	`10`

Get Locations (first page)

To retrieve the first page of locations, call the endpoint with only your API key.

curl -X 'GET' \
  'https://connect.wholechain.com/Integration/Locations' \
  -H 'accept: text/plain' \
  -H 'X-API-KEY: YOUR_API_KEY'

Example With Pagination

The following example requests page 1 with 1 location per page:

curl -X 'GET' \
  'https://connect.wholechain.com/Integration/Locations?PageNumber=1&PageSize=1' \
  -H 'accept: text/plain' \
  -H 'X-API-KEY: YOUR_API_KEY'

Example Response

The response includes pagination information together with the locations returned in the results array.

The example below contains one location and one total page.

{
  "totalPages": 1,
  "pageNumber": 1,
  "pageSize": 1,
  "totalItems": 1,
  "results": [
    {
      "id": "shipFrom_000",
      "urn": "urn:gdst:wholechain.com:location:loc:oceanagroupltd.supplierlocation",
      "details": {
        "tradePartner": {
          "id": "supplier_123",
          "urn": "urn:gdst:wholechain.com:party:suppliertp.0",
          "name": "SupplierTP",
          "pgln": "",
          "connectionType": "OTHER",
          "duns": "123456789"
        },
        "name": "Supplier Location",
        "gln": "9506000140445",
        "dunsPlus4": null,
        "externalIdentifier": "shipFrom_000",
        "extension": "SomeExtension",
        "captainsName": null,
        "address": {
          "city": "City Name",
          "state": "State Name",
          "country": "Country Name",
          "addressLine1": "",
          "addressLine2": "",
          "postalCode": "12345",
          "geoCoordinates": {
            "latitude": 12.345678,
            "longitude": 98.765432
          },
          "displayAddress": "City Name, State Name, Country Name"
        },
        "contact": null,
        "vessel": null,
        "foodFacilityRegistrationNumber": null,
        "locationType": null
      },
      "updateIfExists": false
    }
  ],
  "hasNextPage": false,
  "hasPreviousPage": false
}

Response Pagination Fields

Field	Description
`totalPages`	Total number of pages available.
`pageNumber`	Current page number.
`pageSize`	Number of locations returned per page.
`totalItems`	Total number of locations available.
`results`	Array containing the locations returned for the current page.
`hasNextPage`	Indicates whether another page of results is available.
`hasPreviousPage`	Indicates whether a previous page of results is available.

Important Notes

X-API-KEY is required.
PageNumber is optional.
PageSize is optional.
If PageNumber and PageSize are omitted, the first page of 20 locations is returned.
If PageNumber or PageSize is less than 1, the API returns HTTP 400 with the plain JSON string "PageNumber and PageSize must be greater than 0.".
Some locations are returned with id: null — locations created in the Wholechain UI without an external ID.
Each location is returned inside the results array.
Location responses may also include associated trade partner, address, contact, vessel, and other location information.
Use the Sandbox endpoint for testing and the Production endpoint for live account data.

Was this page helpful?