Finding volumes and books¶

Reading a published book assumed you already knew the coordinates. This guide covers the step before that: working out what is on the shelf at all.

Discovery needs no credentials, though an authenticated caller sees more, because private volumes belonging to your organisation join the results.

In [1]:

  Copied!     
 
from bookshelf import Bookshelf

bs = Bookshelf()
from bookshelf import Bookshelf bs = Bookshelf()

Listing the catalogue¶

search_volumes() with no arguments returns everything you can see.

In [2]:

  Copied!     
 
catalogue = bs.search_volumes()
len(catalogue.items), catalogue.has_more
catalogue = bs.search_volumes() len(catalogue.items), catalogue.has_more

Out[2]:

(15, False)

Each result carries enough to decide whether it is worth opening, including the latest version and edition, so a summary needs no further requests.

In [3]:

  Copied!     
 
for volume in sorted(catalogue.items, key=lambda item: item.name)[:8]:
    licence = volume.discovery.license.root if volume.discovery.license else "-"
    print(f"{volume.name:32} {volume.latest_version or '-':16} {licence}")
for volume in sorted(catalogue.items, key=lambda item: item.name)[:8]: licence = volume.discovery.license.root if volume.discovery.license else "-" print(f"{volume.name:32} {volume.latest_version or '-':16} {licence}")

by-gas-by-sector                 v1.1             NOASSERTION
ceds                             v2021_04_21      CC-BY
fair-shares                      v2025.01.a       NOASSERTION
gdp-ndc-tool                     2023-10          not specified
hadcrut                          v5.1.0.0         NOASSERTION
imf-weo                          v202603          IMF-Data
least-cost                       v1.1.1           NOASSERTION
primap-hist                      v2.7             CC-BY-4.0

Searching¶

The first argument is free text over the name, title and summary.

In [4]:

  Copied!     
 
found = bs.search_volumes("emissions")
[volume.name for volume in found.items]
found = bs.search_volumes("emissions") [volume.name for volume in found.items]

Out[4]:

['ceds',
 'primap-hist',
 'primap-hist-energy-downscaled',
 'rcmip-emissions',
 'un-br-ctf']

Filters narrow it further, and they combine with AND rather than OR. The vocabulary matches the discovery profile a volume is published with: topic, keyword, region, publisher, license, coverage_year, resource_type and deprecated.

In [5]:

  Copied!     
 
[volume.name for volume in bs.search_volumes(license="CC-BY-4.0").items]
[volume.name for volume in bs.search_volumes(license="CC-BY-4.0").items]

Out[5]:

['primap-hist', 'wb-population']

deprecated=False is worth knowing about. A superseded volume stays readable so old analyses keep working, so excluding it is how you avoid building something new on a dataset that has moved on.

In [6]:

  Copied!     
 
active = bs.search_volumes("emissions", deprecated=False)
[volume.name for volume in active.items]
active = bs.search_volumes("emissions", deprecated=False) [volume.name for volume in active.items]

Out[6]:

['ceds',
 'primap-hist',
 'primap-hist-energy-downscaled',
 'rcmip-emissions',
 'un-br-ctf']

Paging¶

The response carries total, limit, offset and has_more. Read has_more rather than comparing counts, and page with offset.

In [7]:

  Copied!     
 
page = bs.search_volumes(limit=5)
print(f"showing {len(page.items)} of {page.total}, more to come: {page.has_more}")

if page.has_more:
    following = bs.search_volumes(limit=5, offset=5)
    print(f"next page starts at {following.items[0].name}")
page = bs.search_volumes(limit=5) print(f"showing {len(page.items)} of {page.total}, more to come: {page.has_more}") if page.has_more: following = bs.search_volumes(limit=5, offset=5) print(f"next page starts at {following.items[0].name}")

showing 5 of 15, more to come: True

next page starts at imf-weo

What versions a volume has¶

A volume holds many books, one per version and edition. bs.volume() asks the platform once and hands back a handle that already knows them all. Printing it is the fastest way to see what is there.

In [8]:

  Copied!     
 
volume = bs.volume("primap-hist")
volume
volume = bs.volume("primap-hist") volume

Out[8]:

Bookshelf Volume 'primap-hist' (versions: 9)

Volume

latest	v2.7_e006
license	CC-BY-4.0
resources	36
size	1.1 GB
description	Comprehensive set of historical greenhouse gas emissions for [...]

Versions

v2.3	editions 005-006
v2.3.1	editions 005-006
v2.4	editions 005-006
v2.4.1	editions 005-006
v2.4.2	editions 005-006
v2.5	editions 005-006
v2.5.1	editions 005-006
v2.6	editions 005-006
v2.7	editions 005-006

Access

volume["v2.7"]

Versions sort component by component, comparing numeric runs as numbers, so v2.10 lands after v2.9 instead of before it. latest is therefore the newest version rather than the last one published.

In [9]:

  Copied!     
 
volume.versions, volume.latest, volume.editions(volume.latest)
volume.versions, volume.latest, volume.editions(volume.latest)

Out[9]:

(('v2.3',
  'v2.3.1',
  'v2.4',
  'v2.4.1',
  'v2.4.2',
  'v2.5',
  'v2.5.1',
  'v2.6',
  'v2.7'),
 'v2.7',
 (5, 6))

From discovery to data¶

Indexing the volume by version resolves the book, defaulting to its newest edition. Leave the version off as well and you get the newest book in the volume.

In [10]:

  Copied!     
 
entry = volume.book()["by_region"]
entry.query(year_min=2018, year_max=2020, top_n=5).iloc[:5, :3]
entry = volume.book()["by_region"] entry.query(year_min=2018, year_max=2020, top_n=5).iloc[:5, :3]

Out[10]:

		2018	2019	2020
category	gwp_context
0	AR6GWP100	51119499.0	51983668.0	49955598.0
	AR5GWP100	50883661.0	51739829.0	49701639.0
	AR4GWP100	50351551.0	51196267.0	49186145.0
M.0.EL	AR6GWP100	49587740.0	50170250.0	48553159.0
M.0.EL	AR5GWP100	49353822.0	49928687.0	48301725.0

A volume reports only what it has published, because a draft is not something a consumer can read. The full catalogue rows, drafts included, are on the command line and in BookshelfClient.

From the command line¶

The same catalogue is searchable without writing any Python, which is often faster when you are just orienting yourself.

bookshelf search emissions
bookshelf search --licence CC-BY-4.0 --no-deprecated
bookshelf search --facets            # the valid values for each filter
bookshelf show primap-hist           # one volume, its versions and editions
bookshelf show primap-hist@v2.6/by_region

Every command takes --json for a machine readable form.