Extract Nested Array Values from API JSON Using JSONPath

Use $..propertyName to Grab Every Nested Array Value in One Shot

Before you write another loop inside a loop inside a loop — stop. A single JSONPath expression like $..price can pull every price value from a deeply nested API response, no matter how many arrays those values are buried inside. That's the power of recursive descent, and it's the first technique every developer working with JSON APIs should have in their toolkit.

API responses today are rarely flat. A typical e-commerce API might return an order object containing an array of shipments, each containing an array of items, each containing an array of discounts. If you need every discount value across all shipments and all items, you don't need to traverse that tree manually. JSONPath handles it for you — and in this guide, we'll walk through seven practical techniques to extract nested array values cleanly, efficiently, and without breaking a sweat.

1. Understand the Recursive Descent Operator (..)

The double-dot operator is the single most important token in JSONPath when dealing with nested arrays. It tells the evaluator to search at every level of the JSON tree, not just the current one.

Consider this API response:

{
  "orders": [
    {
      "id": "ORD-1001",
      "items": [
        { "sku": "A1", "price": 29.99 },
        { "sku": "B2", "price": 49.99 }
      ]
    },
    {
      "id": "ORD-1002",
      "items": [
        { "sku": "C3", "price": 12.50 },
        { "sku": "D4", "price": 89.00 }
      ]
    }
  ]
}

To extract every price value regardless of nesting depth, use:

$.orders..price

This returns: [29.99, 49.99, 12.50, 89.00]. One expression, four values, zero manual iteration. If your API adds a new nesting level in a future version, the same expression still works.

2. Target Specific Array Indices When You Need Precision

Recursive descent is powerful, but sometimes you need surgical precision. Maybe you only want the price of the first item in each order. JSONPath lets you combine array indexing with nested traversal.

Use this expression:

$.orders[*].items[0].price

The [*] wildcard iterates over every element in the orders array, while [0] selects only the first item from each order's items array. The result: [29.99, 12.50].

This approach is ideal when you know the exact structure of the response and only need specific elements. It's also faster than recursive descent because the evaluator doesn't need to search every node in the tree.

3. Use Filter Expressions to Extract Conditional Values

Real-world APIs return mixed data. You rarely want everything — you want values that match a condition. JSONPath supports filter expressions using the [?(...)] syntax.

Say you want only the prices above $30.00 from the response above:

$.orders..items[?(@.price > 30)].price

Result: [49.99, 89.00]. The @ symbol refers to the current element being evaluated. You can chain multiple conditions with && and ||:

$.orders..items[?(@.price > 20 && @.price < 80)].price

This returns [29.99, 49.99], filtering out both the $12.50 and $89.00 items.

4. Handle Deeply Nested Arrays with Multi-Level Wildcards

Some API responses go several levels deep. A weather API might return countries, each with regions, each with cities, each with stations, each with readings. To extract every temperature reading regardless of how deep it sits:

$..readings[*].temperature

Or more aggressively:

$..temperature

The difference matters. The first expression only matches temperature fields that live inside readings arrays. The second matches any temperature field anywhere in the document. If the API also includes a top-level averageTemperature field that you don't want, the more specific path is safer.

Rule of thumb: use the broadest expression only when you trust the API's field naming. Use specific paths when field names might collide across different object types.

5. Extract Nested Objects Alongside Array Values

Sometimes you don't just want a scalar value — you want the entire object containing it. This is common when you need to correlate multiple fields.

Using our earlier example, if you want every item object where the price exceeds $30:

$.orders..items[?(@.price > 30)]

This returns the full objects:

[
  { "sku": "B2", "price": 49.99 },
  { "sku": "D4", "price": 89.00 }
]

You can then process these objects in your application code without making a second API call or re-parsing the original response. This pattern is especially useful in data pipelines where you need to transform and forward filtered subsets of a larger payload.

6. Combine Slices and Filters for Paginated Extraction

Large API responses often include pagination or batching. If an array contains 500 elements but you only need the first 50 that match a condition, combine array slicing with filtering:

$.data[0:50][?(@.status == 'active')].id

The [0:50] slice limits evaluation to the first 50 elements, and the filter then narrows that subset to active records. On a response with 500 items where roughly 60% are typically active, this expression processes only 50 elements instead of all 500, reducing evaluation time by approximately 90%.

Not all JSONPath implementations support slicing equally, so test with your specific library. Popular implementations like Jayway (Java), jsonpath-plus (JavaScript), and GoJSONPath all handle slices, but behavior can differ with negative indices and step parameters.

7. Validate Your Expressions Against Real API Responses

A JSONPath expression that works on a simplified example might fail on a real API response with unexpected nulls, missing fields, or type inconsistencies. Always test against actual data.

Here's a practical workflow:

• Capture a real API response using your HTTP client or a tool like Postman
• Paste it into a JSONPath evaluator or testing tool
• Iterate on your expression until it returns exactly what you expect
• Add edge-case tests: empty arrays, null values, missing fields, and deeply nested structures

One common gotcha: if a nested array is sometimes present and sometimes absent, a recursive descent expression will silently skip the absent case. This is usually the behavior you want, but it can mask API contract changes. If you're building production code, log the count of matched values and alert on unexpected drops.

Putting It All Together

Extracting nested array values from API JSON responses doesn't require complex traversal logic. With the right JSONPath expressions, you can pull exactly the data you need in a single line — whether that's every value at any depth, filtered subsets, specific array indices, or full objects matching a condition.

Start with recursive descent (..) for broad extraction, narrow down with wildcards and indices when you need precision, and always validate against real API data before shipping to production. These seven techniques cover the vast majority of nested array extraction scenarios you'll encounter in real APIs.