jsonparse: ctrl-f for json

jsonparse is a simple JSON parsing library. Extract what's needed from key:value pairs.

What's New

• Python 2.7 compat. 😅 😌
• A new function, find_value, has been added. This function will return all keys of the matched value. 😀
• CLI tool. Parse json text files or stdin via the command line 🎉

Python Library

Install

pip install jsonparse

Quickstart

Here is a quick example of what jsonparse is able to do.

from jsonparse import find_key, find_keys, find_key_chain, find_key_value, find_value

data = [{
  "key0":
    {
      "key1": "result",
      "key2":
        {
          "key1": "result1",
          "key3": {"key1": "result2"}
        }
    }
}]

find_key(data, 'key1')
['result2', 'result1', 'result']

find_key_chain(data, ['key0', 'key2', 'key3', 'key1'])
['result2']

➕ See additional documentation in the API section below.

CLI tool

Install

pip install jsonparse

Quickstart

Summary of cli commands. For complete information, jp --help

Note, jsonparse and jp are equivalent.

jp key key1 --file text.json

jp keys key1 key2 key3 --file text.json

jp key-chain my '*' chain --file text.json

jp key-value key1 '"result"' --file text.json

echo '{"key1": {"key2": 5}}' | jp key key2

jp value null --file text.json

jp value 42 --file text.json

jp value '"strValue"' --file text.json

API

• jsonparse functions
  • find_key
  • find_keys
  • find_key_chain
  • find_key_value
  • find_value

The API examples using the following test data.

data = [
    {"key": 1},
    {"key": 2},
    {"my": 
        {"key": 
            {
                "chain": "A",
                "rope": 5,
                "string": 1.2,
                "cable": False
            }
        }
    },
    {"your":
    	{"key":
            {
                "chain": "B",
                "rope": 7,
                "string": 0.7,
                "cable": True
            }
    	}
    }
]

---

Functions

from jsonparse import find_key, find_keys, find_key_chain, find_key_value, find_value

---

find_key

find_key(data: dict | list | OrderedDict, key: str) -> list

    Will return all values of the matched key.

find_key(data, 'chain')
['A', 'B']

find_key(data, 'key')
[1, 2, {'chain': 'A', 'rope': 5, 'string': 1.2, 'cable': False}, {'chain': 'B', 'rope': 7, 'string': 0.7, 'cable': True}]

---

find_keys

find_keys(data: dict | list | OrderedDict, keys: list, group: bool = True) -> list

    The default return value is a two dimensional list. [ [], [], ...].

    To return all values as a one dimensional list, set group=False.

    The ordering of the keys does not matter.

find_keys(data, ['rope', 'cable'])
[[5, False], [7, True]]

find_keys(data, ['rope', 'cable'], group=False)
[5, False, 7, True]

---

find_key_chain

find_key_chain(data: dict | list | OrderedDict, keys: list) -> list

    The key chain is an ordered list of keys. The chain needs to start at the root level of the nested data.

    Wildcard * can be used as key(s) to match any.

find_key_chain(data, ['my', 'key', 'chain'])
['A']

find_key_chain(data, ['key'])
[1, 2]

find_key_chain(data, ['*', 'key', 'chain'])
['A', 'B']

find_key_chain(data, ['*', 'key', '*'])
['A', 5, 1.2, False, 'B', 7, 0.7, True]

---

find_key_value

find_key_value(data: dict | list | OrderedDict, key: str, value: str | int | float | bool | None) -> list

    The returned list contains the dictionaries that contain the specified key:value pair.

find_key_value(data, 'cable', False)
[{'chain': 'A', 'rope': 5, 'string': 1.2, 'cable': False}]

find_key_value(data, 'chain', 'B')
[{'chain': 'B', 'rope': 7, 'string': 0.7, 'cable': True}]

---

find_value

find_value(data: dict | list | OrderedDict, value: str | int | float | bool | None) -> list

    Will return all keys of the matched value.

find_value(data, 'A')
['chain']

find_value(data, False)
['cable']

Python 2.7 Usage

• 2.7 does not guarantee ordering of dictionary's. If ordering matters, use OrderedDict for all dictionary's in the data.

Web API

Documentation

Visit the swagger API documentation

All endpoints are HTTP POST requests where you include the searchable JSON data in the request body.

Brief Endpoint Overiew

POST /v1/key/{key}
POST /v1/keys?key=1&key=2&key=3&key=4...
POST /v1/keychain?key=1&key=2&key=3&key=4...
POST /v1/keyvalue?key=a&value=1
POST /v1/value/{value}

Quickstart

Let's practice using the public, free-to-use-no-authentication, web API hosted in GCP Cloud Run.

We are POST'ing the JSON data with curl, requesting to search for the key, 'key1'. The found key values are returned as JSON.

curl -X POST "https://jsonparse.dev/v1/key/key1" \
-H 'Content-Type: application/json' \
-d '[{"key0":{"key1":"result","key2":{"key1":"result1","key3":{"key1":"result2"}}}}]'

["result2","result1","result"]

OR (using python and requests library)

import requests

data = [{
    "key0":
    {
        "key1": "result",
        "key2":
        {
            "key1": "result1",
            "key3": {"key1": "result2"}
        }
    }
}]

requests.post('https://jsonparse.dev/v1/key/key1', json=data).json()

['result2', 'result1', 'result']

Self-Hosted

pip install "jsonparse[webapi]"

gunicorn -b 0.0.0.0:8000 jsonparse.webapi:app

Alternatively, run the docker container

docker run -d ctomkow/jsonparse