1. Layouts
  2. Retrieve Layouts

Layouts

Retrieve Layouts

Retrieve Single Layout

GET
`/v1/locations/:location/layouts/:layout`

Retrieve detailed information about a specific layout within your location.

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

//The result will be a single layout object
const layout = response.data;

List Layouts

GET
`/v1/locations/:location/layouts`

Retrieves a paginated list of layouts with comprehensive filtering, sorting, and searching capabilities. This endpoint provides flexible querying options to find layouts based on various criteria.

Basic Layout Retrieval

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

const layouts = response.data;

Response Structure

js 
        {
    "message": "10 layouts retrieved",
    "data": [
        // Array of layout objects
    ],
    "status": 200,
    "errors": [],
    "code": null,
    "pagination": {
        "object": "pagination",
        "page": 1,
        "limit": 1000,
        "total_count": 10,
        "has_more": false
    },
    "endpoint": null
}

Filtering

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

Parameter Description
path Filter by specific path
code Filter by layout code
metadata Filter by metadata properties

Filtering Examples

  • Filter by Path:
    Retrieve layouts based on their hierarchical structure. Here's what it does:

    1. When path=all: Returns all layouts for the location without filtering by parent-child relationships.
    2. When path=some-specific-path: Returns only layouts that are direct children of the layout identified by the last component of the specified path.
    3. Without the path parameter: It defaults to showing only top-level layouts (those with no parent).

This parameter is useful for navigating through hierarchical layout structures, allowing you to either view the entire layout hierarchy at once (path=all) or to view specific levels of the hierarchy (by specifying a path to that level).

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

const layouts = response.data;

Another example request with path=all

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

const layouts = response.data;
NOTE

When using path filters with forward slashes (/), ensure proper URL encoding. Most modern HTTP clients handle this automatically, but you may need to manually encode "/" as "%2F" in some cases.

  • Filter by Layout Code:
    Retrieve layouts with a specific code
js 
        const response = await fetch(`https://api.packagex.io/v1/locations/${location_id}/layouts?code=la1`, {
  method: "GET",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
}).then((res) => res.json());

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

const layouts = response.data;

Pagination

The API implements pagination to manage large result sets efficiently. The API response includes a pagination object with the following properties:

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

To retrieve the next page of results:

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

const layouts = response.data;
const pagination = response.pagination;

Sorting

Control the order of results using:

Parameter Type Default Description
order_by string hierarchy Field to sort by, supported values: name, nested_name, hierarchy, 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 hierarchy in ascending order asc

Example with sorting:

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

const layouts = response.data;
const pagination = response.pagination;

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

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

const layouts = response.data;
const pagination = response.pagination;

You can also include search_strategy parameter along with search. The search_strategy parameter determines how multiple search terms are combined when performing searches across database records.

Available Strategies

  • match_all (Default):

    • Require ALL search terms to be present in results.

  • match_some

    • Allows ANY search term to match results.

Impact on Search Results

  • When using match_all

    • Smaller, more precise result sets.

  • When using match_some

    • Larger, more diverse result sets.

Example Scenarios

  • Using match_all
js 
        const response = await fetch(`https://api.packagex.io/v1/locations/${location_id}/layouts?search=counter 4&search_strategy=match_all`, {
  method: "GET",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
}).then((res) => res.json());

// Only matches records containing BOTH "counter" AND "4"
const layouts = response.data;
const pagination = response.pagination;
  • Using match_some
js 
        const response = await fetch(`https://api.packagex.io/v1/locations/${location_id}/layouts?search=counter 4&search_strategy=match_some`, {
  method: "GET",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
}).then((res) => res.json());

// Matches records containing EITHER "counter" OR "4"
const layouts = response.data;
const pagination = response.pagination;
Previous <- Add Layouts
Next Delete Layouts ->