1. Locations
  2. Retrieve Locations

Locations

Retrieve Locations

Retrieve detailed information about a specific location. This endpoint provides comprehensive location data.

GET
`/v1/locations/:location`

URL Parameters

  • location_id (required): The unique identifier of the location, prefixed with loc_
js 
        const response = await fetch(`https://api.packagex.io/v1/locations/${location_id}`, {
  method: "GET",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
}).then((res) => res.json());

const location = response.data;

List Locations

Retrieve a list of locations with comprehensive filtering, searching, and pagination capabilities. Two endpoint variations are available:

Standard List Endpoint

Provides detailed location information with pagination support.

GET
`/v1/locations`
js 
        const response = await fetch(`https://api.packagex.io/v1/locations`, {
  method: "GET",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json"
  }
}).then((res) => res.json());

const locations = response.data;

Cached List Endpoint

Optimized for quick access to basic location data without pagination.

GET
`/v1/locations?cache=1`
js 
        const response = await fetch(`https://api.packagex.io/v1/locations?cache=1`, {
  method: "GET",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json"
  }
}).then((res) => res.json());

const locations = response.data;

Query Parameters

Filtering

The API supports comprehensive filtering of locations through query parameters. Multiple filters can be combined to refine your results.

Parameter Type Description
group_id or group string Filter locations by group association.
user_id or user string Filter locations by user access.
metadata string Filter by metadata key-value pairs.

Filtering Examples

  • Filter by group_id or group
js 
        const response = await fetch(`https://api.packagex.io/v1/locations?group_id=grp_abc123xyz`, {
  method: "GET",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json"
  }
}).then((res) => res.json());

const locations = response.data;
const pagination = response.pagination;
  • Filter by user_id or user
js 
        const response = await fetch(`https://api.packagex.io/v1/locations?user_id=user_abc123xyz`, {
  method: "GET",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json"
  }
}).then((res) => res.json());

const locations = response.data;
const pagination = response.pagination;
  • Filter by metadata
js 
        const response = await fetch(`https://api.packagex.io/v1/locations?metadata.purpose=testing`, {
  method: "GET",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json"
  }
}).then((res) => res.json());

const locations = response.data;
const pagination = response.pagination;

Pagination

The response includes a pagination object with the following properties:

  • has_more - Indicates if there are more locations available
  • page - Current page number (default: 1)
  • limit - Number of results per page (default: 25)
  • total_count - Total number of locations in the database.

To retrieve the next page of results:

js 
        const response = await fetch(`https://api.packagex.io/v1/locations?page=1&limit=25`, {
  method: "GET",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  }
}).then((res) => res.json());

const locations = response.data;
const pagination = response.pagination;

Sorting

Control the order of results using:

Parameter Type Default Description
order_by string created_at Field to sort by, supported values: name, code, created_at, updated_at
direction string asc Sort direction, supported values: asc, desc

If no sorting parameter is specified, the system defaults to sorting by created_at in ascending order asc

Example with sorting:

js 
        const response = await fetch(`https://api.packagex.io/v1/locations?order_by=updated_at&direction=desc`, {
  method: "GET",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  }
}).then((res) => res.json());

const locations = response.data;
const pagination = response.pagination;

The API provides advanced full-text search capabilities through the search parameter, allowing you to search locations using fuzzy, typo-tolerant matching across multiple fields. The search functionality examines key location properties including:

  • group_names
  • name
  • code
  • metadata
js 
        const response = await fetch(`https://api.packagex.io/v1/locations?search=My HQ`, {
  method: "GET",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  }
}).then((res) => res.json());

const locations = response.data;
const pagination = response.pagination;

Each location in the search results includes a special _search object that provides detailed information about the match:

js 
        "_search": {
  "group_names": ["group_abc", "group_xyz"],
  "name": "<mark>My HQ</mark>",
  "code": "MQ",
  "relevance_score": 0.8,
  "query": "My HQ"
}

The _search object includes highlighted matches using <mark> tags, making it easy to emphasize matching text in user interfaces. It also provides a relevance score between 0 and 1, where higher values indicate better matches. By default, search results are ordered by relevance score to show the best matches first. However, you can override this by specifying an order_by parameter to sort by other fields like created_at, updated_at, name, code. The search functionality can be combined with other filter parameters to refine your results further.

Previous <- Create & Update Locations
Next Delete Location ->