ScreenshotNeo

BlogHow-to

Parsing JSON with JMESPath in Python

Decode JSON into Python data, then use JMESPath expressions to select, filter, and reshape it. Includes runnable examples, edge cases, and error fixes.

By the ScreenshotNeo team30 September 20268 min read

Parsing JSON with JMESPath in Python

To parse JSON with JMESPath in Python, first decode the JSON text into ordinary Python values with json.loads() (or use the decoded response from an HTTP client), then evaluate a JMESPath expression with the jmespath package. JMESPath expressions select and transform JSON-shaped data; they do not parse JSON text by themselves.

import json
import jmespath

document = json.loads('{"people": [{"name": "Mina", "active": true}]}')
name = jmespath.search("people[0].name", document)
print(name)  # Mina

Install the package with python -m pip install jmespath. This uses the Python implementation, jmespath.py, which the official library list describes as fully compliant with the JMESPath specification. See the official tutorial, specification, and implementation list for exact language behavior.

1. Decode JSON, then query it

These are separate steps. json.loads() converts a JSON string into Python dictionaries, lists, strings, numbers, booleans, and None. The JMESPath evaluator receives that data structure and an expression. If you already have decoded JSON from a library, pass that value directly to JMESPath.

JMESPath evaluates expressions against decoded Python data, so decoding and querying are distinct steps.
JMESPath evaluates expressions against decoded Python data, so decoding and querying are distinct steps.
import json
import jmespath

json_text = '''{
  "service": "catalog",
  "owner": {"name": "Mina", "team": "platform"},
  "items": [
    {"id": 12, "name": "Keyboard", "active": true, "price": 89.5},
    {"id": 13, "name": "Cable", "active": false, "price": 9.0}
  ]
}'''

document = json.loads(json_text)
print(jmespath.search("owner.name", document))  # Mina

The result is ordinary Python data: a scalar, list, dictionary, or None. A JMESPath expression is therefore useful when you want a compact, reusable description of which parts of a JSON document to extract. For application-specific branching or side effects, regular Python may be simpler.

2. Select fields, nested values, and array elements

Identifiers select object keys. A dot composes nested access, and square brackets select an array index. Array indexes begin at zero.

Need Expression Example result
Top-level field service "catalog"
Nested field owner.team "platform"
Field in first array item items[0].name "Keyboard"
Last item items[-1].name "Cable"
queries = ["service", "owner.team", "items[0].name", "items[-1].price"]
for expression in queries:
    print(expression, "=>", jmespath.search(expression, document))

Use an expression that matches the shape of the input. If the root value is a list, an expression beginning with an object key will not behave like an expression on an object. Inspect a small input sample and try simple field access before adding projections, filters, or functions.

3. Project and filter collections

A projection applies an expression to each item in a collection. For example, items[*].name returns the names from the items array. A filter expression selects array entries meeting a condition.

Projections and filters help extract values from collections, but missing projected values can affect the output list.
Projections and filters help extract values from collections, but missing projected values can affect the output list.
names = jmespath.search("items[*].name", document)
active_items = jmespath.search("items[?active == `true`].name", document)

print(names)        # ['Keyboard', 'Cable']
print(active_items) # ['Keyboard']

JMESPath uses backticks to express JSON literals in expressions, such as `true` and `10`. This differs from putting a quoted string into the expression. For a string comparison, use a quoted JMESPath string literal, for example items[?name == 'Cable']. Keep expressions readable by assigning them to a variable when they are long or reused.

Projection behavior deserves attention: a projected expression that evaluates to null for an item may omit that result from the projected list. Do not assume the output list preserves one position for every input item. If positional correspondence matters, select the full items and process them in Python, or verify the exact expression semantics with representative data.

4. Build a smaller result object

A multi-select hash constructs an object with chosen fields. This is useful when downstream code should receive a stable subset rather than the entire source record.

summary = jmespath.search(
    "{team: owner.team, first_item: items[0].name, count: length(items)}",
    document,
)
print(summary)
# {'team': 'platform', 'first_item': 'Keyboard', 'count': 2}

Field labels inside the braces define output keys. Expressions after the colons define values. You can also use multi-select lists to create a list with a fixed sequence of results, but remember that downstream code must then rely on position rather than a descriptive key.

5. Use functions with the expected types

JMESPath includes functions for common transformations and inspection. The function signatures specify argument types and arity; a function receiving the wrong type can produce an evaluation error. For example, length() operates on supported strings, arrays, or objects, while to_number() attempts a conversion.

print(jmespath.search("length(items)", document))  # 2
print(jmespath.search("type(items[0].price)", document))  # number

raw = {"count": "42"}
print(jmespath.search("to_number(count)", raw))  # 42

Conversions are not a substitute for validating external data. A string may be malformed or a field may have a different shape than expected. Check the result and handle invalid or absent input in your application. Consult the function section of the specification for supported functions, argument rules, and evaluation semantics.

6. Query JSON from a file or HTTP response

For a file, decode with json.load(). For an HTTP response, use the response library’s JSON decoder and pass the resulting Python structure to jmespath.search(). Here is a complete file example:

import json
import jmespath

with open("payload.json", encoding="utf-8") as file:
    payload = json.load(file)

expression = "records[*].{id: id, label: name}"
result = jmespath.search(expression, payload)
print(json.dumps(result, indent=2, ensure_ascii=False))

For HTTP, this example uses Requests and leaves the endpoint to your application:

import requests
import jmespath

response = requests.get("https://example.com/api/data", timeout=20)
response.raise_for_status()
payload = response.json()

result = jmespath.search("records[*].name", payload)
print(result)

The example URL is a placeholder; replace it with the API endpoint you are authorized to call. Set an appropriate timeout and check the HTTP status before querying. If the response body is not valid JSON, decoding fails before JMESPath runs.

7. Compile expressions reused in a loop

For a one-off lookup, jmespath.search(expression, data) is straightforward. If the same expression is evaluated repeatedly against many documents, compile it once and reuse the parsed expression:

expression = jmespath.compile("items[*].{id: id, name: name}")

for payload in documents:
    selected = expression.search(payload)
    process(selected)

This avoids reparsing the expression for each document. It does not make a universal speed guarantee: runtime depends on input size, expression shape, and surrounding work. Measure with representative data if query cost matters. Keep payload sizes bounded and avoid repeatedly decoding identical JSON when the already-decoded object can be reused.

8. Handle absent keys, nulls, and malformed input

The JSON data model includes null, which Python represents as None. An unknown identifier evaluates to null under the specification, so a missing key can produce None rather than an exception. That means a missing field and an explicitly null field may need additional checks if your application treats them differently.

result = jmespath.search("owner.email", document)
if result is None:
    print("email is missing or null")

Validate the shape at boundaries where it matters. For example, a filter expecting records should receive a list; a field used by arithmetic or an aggregation should have a compatible value. Catch JSON decoding errors separately from JMESPath evaluation errors so the failure points remain clear.

import json
import jmespath

try:
    payload = json.loads(raw_text)
except json.JSONDecodeError as error:
    raise ValueError("The response was not valid JSON") from error

try:
    result = jmespath.search("items[*].name", payload)
except jmespath.exceptions.JMESPathError as error:
    raise ValueError("The JMESPath query could not be evaluated") from error

The specification names error classes including invalid type, invalid value, unknown function, and invalid arity. How an implementation signals an evaluation error can vary; catch the package’s JMESPath error base class and log the expression and safe context needed to diagnose it. Avoid logging credentials or sensitive source records.

9. Troubleshooting common problems

Symptom Likely cause Fix
ModuleNotFoundError: No module named 'jmespath' Package is not installed in the Python environment running the script. Run python -m pip install jmespath with the same interpreter, then rerun.
JSON decoding error Input is empty, malformed, or not actually JSON. Inspect the raw response, status code, and content type; decode before querying.
Result is None A key is absent, explicitly null, or the expression is aimed at the wrong shape. Print or inspect a small sanitized input; verify root object versus array and spelling.
Function evaluation error Wrong argument type, invalid value, unknown function, or wrong number of arguments. Check the function signature and actual field types; add explicit validation or conversion.
Projection has fewer results than input records Projected expressions yielding null can be omitted. Check missing fields and choose an expression or Python post-processing that preserves correspondence.
Unexpected literal comparison JSON booleans/numbers in expressions need JSON literal syntax. Use backtick literals, such as `false` or `3`; use quoted JMESPath strings for text.

10. Performance, reliability, and cost

JMESPath is a query language, not a remote service: evaluating an expression against an in-memory Python object does not incur an API fee. The practical costs are local CPU and memory, JSON decoding, and any network request used to obtain the document. The official sources cited here do not provide a comparative benchmark, so avoid assuming it is faster than handwritten Python traversal.

For reliable data handling, use HTTP timeouts, check response status, handle decoding and query errors distinctly, and validate required fields before using results. Test expressions against examples that include empty arrays, missing fields, nulls, and unexpected types. For repeated queries, compile the expression once. Keep credentials out of logs, and do not treat a successful query as proof that the original payload meets your whole application schema.

11. Or skip the browser setup

If the JSON you need comes from a webpage screenshot workflow, ScreenshotNeo offers a one-call screenshot API. One GET request can return PNG, JPEG, WebP, or PDF; the API documentation lists the request options.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp
import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

ScreenshotNeo removes supported cookie banners, newsletter popups, and chat widgets before capture. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed; response headers identify the page verdict and billing outcome. Its MCP server lets AI agents use screenshot, page information, and PDF capture tools. The free plan includes 1,000 screenshots per month with no card, and paid plans start at $5 for 3,000 screenshots.

Learn about ScreenshotNeo or sign up for 1,000 free screenshots a month, no card required.

12. FAQ

Does JMESPath parse a JSON string directly?

No. Decode the string to Python data first with json.loads(), then query the resulting structure.

What does a missing key return?

The specification defines unknown identifiers as null, which maps to Python None. Check for that result before using it.

Can I use a JMESPath expression in another language?

JMESPath has implementations in multiple languages, and the project publishes a specification and compliance suite. Consult the implementation list for a target language and verify its supported behavior.

When should I use Python instead?

Use Python when the task requires application-specific branching, side effects, or logic that is clearer as ordinary control flow. JMESPath is useful for declarative selection and shaping of JSON-like data.

References