Ijson is an iterative JSON parser with standard Python iterator interfaces.

Installation

Ijson is hosted in PyPI, so you should be able to install it via pip:

pip install ijson

Binary wheels are provided for major platforms and python versions. These are built and published automatically using cibuildwheel via GitHub Actions.

Usage

All usage example will be using a JSON document describing geographical objects:

{
  "earth": {
    "europe": [
      {"name": "Paris", "type": "city", "info": { ... }},
      {"name": "Thames", "type": "river", "info": { ... }},
      // ...
    ],
    "america": [
      {"name": "Texas", "type": "state", "info": { ... }},
      // ...
    ]
  }
}

High-level interfaces

ijson works by continuously reading data from a JSON stream provided by the user. This is presented as a file-like object. In particular it must provide a read(size) method returning either bytes (preferably) or str. Example file-like objects are files opened with open, HTTP/HTTPS requests made using urllib.request.urlopen, socket.socket objects, and more.

The most common usage of ijson is to yield native Python objects located under a prefix. This is done using the items function. Here's how to process all European cities:

import ijson
f = urlopen('http://.../')
objects = ijson.items(f, 'earth.europe.item')
cities = (o for o in objects if o['type'] == 'city')
for city in cities:
    do_something_with(city)

For how to build a prefix see the prefix section below.

Other times it might be useful to iterate over object members rather than objects themselves (e.g., when objects are too big). In that case one can use the kvitems function instead:

import ijson
f = urlopen('http://.../')
european_places = ijson.kvitems(f, 'earth.europe.item')
names = (v for k, v in european_places if k == 'name')
for name in names:
    do_something_with(name)

Lower-level interfaces

Sometimes when dealing with a particularly large JSON payload it may worth to not even construct individual Python objects and react on individual events immediately producing some result. This is achieved using the parse function: