Need to extract specific data from complex JSON structures? This guide covers everything you need to know about querying JSON with JSONPath via API, including syntax, operators, and implementation examples.
What is JSONPath?
JSONPath is a query language for JSON, similar to XPath for XML. It allows you to extract specific values from JSON documents using path expressions without writing custom parsing code.
For example, $.store.books[0].title extracts the title of the first book from a store object.
JSONPath Syntax
Key operators and expressions:
Basic Operators
$ - Root object. . - Child operator. [] - Array index or filter.
Wildcards and Recursion
* - All children. .. - Recursive descent (search all levels).
Filters
[?(@.price < 10)] - Filter by condition. Supports comparison operators.
$.. to find all occurrences of a key anywhere in the document.
Using the JSON Path API
TinyFn provides a simple endpoint to query JSON:
POST https://api.tinyfn.io/v1/json/path
Headers: X-API-Key: your-api-key
Content-Type: application/json
{
"json": {
"store": {
"books": [
{"title": "Book 1", "price": 9.99},
{"title": "Book 2", "price": 15.99},
{"title": "Book 3", "price": 7.50}
]
}
},
"path": "$.store.books[?(@.price < 10)].title"
}{
"result": ["Book 1", "Book 3"],
"count": 2,
"path": "$.store.books[?(@.price < 10)].title"
}Parameters
| Parameter | Type | Description |
|---|---|---|
json |
object | The JSON document to query |
path |
string | JSONPath expression |
single |
boolean | Return only first match (default: false) |
Code Examples
JavaScript / Node.js
const data = {
store: {
books: [
{ title: 'Book 1', price: 9.99, category: 'fiction' },
{ title: 'Book 2', price: 15.99, category: 'science' },
{ title: 'Book 3', price: 7.50, category: 'fiction' }
]
}
};
// Get all book titles
const response = await fetch(
'https://api.tinyfn.io/v1/json/path',
{
method: 'POST',
headers: {
'X-API-Key': 'your-api-key',
'Content-Type': 'application/json'
},
body: JSON.stringify({
json: data,
path: '$.store.books[*].title'
})
}
);
const { result } = await response.json();
console.log(result); // ['Book 1', 'Book 2', 'Book 3']
// Get fiction books under $10
const filteredResponse = await fetch(
'https://api.tinyfn.io/v1/json/path',
{
method: 'POST',
headers: {
'X-API-Key': 'your-api-key',
'Content-Type': 'application/json'
},
body: JSON.stringify({
json: data,
path: '$.store.books[?(@.category=="fiction" && @.price<10)]'
})
}
);
console.log((await filteredResponse.json()).result);
// [{ title: 'Book 1', ... }, { title: 'Book 3', ... }]Python
import requests
data = {
'store': {
'books': [
{'title': 'Book 1', 'price': 9.99},
{'title': 'Book 2', 'price': 15.99},
{'title': 'Book 3', 'price': 7.50}
]
}
}
# Get cheap book titles
response = requests.post(
'https://api.tinyfn.io/v1/json/path',
json={
'json': data,
'path': '$.store.books[?(@.price < 10)].title'
},
headers={'X-API-Key': 'your-api-key'}
)
result = response.json()['result']
print(result) # ['Book 1', 'Book 3']cURL
curl -X POST "https://api.tinyfn.io/v1/json/path" \
-H "X-API-Key: your-api-key" \
-H "Content-Type: application/json" \
-d '{
"json": {"store": {"books": [{"title": "Book 1", "price": 9.99}]}},
"path": "$.store.books[*].title"
}'Common Use Cases
- API Response Parsing: Extract specific fields from large responses
- Configuration: Query nested config values
- Data Transformation: Select and reshape data structures
- Testing: Assert specific values in JSON responses
- ETL Pipelines: Extract data during transformations
Best Practices
- Be specific: Avoid overly broad queries that return too much data
- Use filters: Narrow results with filter expressions
- Test paths: Validate queries with sample data first
- Handle empty results: Check for empty arrays in your code
Use via MCP
Your AI agent can call this tool directly via Model Context Protocol — no HTTP code needed. Add TinyFn to Claude Desktop, Cursor, or any MCP client:
{
"mcpServers": {
"tinyfn-json": {
"url": "https://api.tinyfn.io/mcp/json/",
"headers": {
"X-API-Key": "your-api-key"
}
}
}
}See all json tools available via MCP in our JSON MCP Tools for AI Agents guide.