MediaCloud Python API Client

This is a python client for accessing the MediaCloud API v4. This allows you to perform cross-platform searches and also browse our collection/source/feed directory.

pylint pytest

Usage

First sign up for an API key. Then

pip install mediacloud

Check CHANGELOG.md for a detailed history of changes.

Examples

Take a look at the test in the mediacloud/test/ module for more detailed examples.

Count Stories Matching a Query

import mediacloud.api
US_NATIONAL_COLLECTION = 34412234
mc_search = mediacloud.api.SearchApi(YOUR_MC_API_KEY)
all_stories = []
pagination_token = None
more_stories = True
while more_stories:
    page, pagination_token = mc_search.story_list('robots', start_date= , end_date= collection_ids=[US_NATIONAL_COLLECTION])
    all_stories += page
    more_stories = pagination_token is not None
print(f"Retrived {len(all_stories)} matching stories")

Page Through Stories Matching a Query

import mediacloud.api
INDIA_NATIONAL_COLLECTION = 34412118
mc_search = mediacloud.api.SearchApi(YOUR_MC_API_KEY)
all_stories = []
pagination_token = None
more_stories = True
while more_stories:
    page, pagination_token = mc_search.story_list('modi AND biden', collection_ids=[INDIA_NATIONAL_COLLECTION],
                                                  pagination_token=pagination_token)
    all_stories += page
    more_stories = pagination_token is not None
print(f"Retrived {len(all_stories)} matching stories")

Fetch all Sources in a Collection

import mediacloud.api
INDIA_NATIONAL_COLLECTION = 34412118
SOURCES_PER_PAGE = 100  # the number of sources retrieved per page
mc_directory = mediacloud.api.DirectoryApi(YOUR_MC_API_KEY)
sources = []
offset = 0   # offset for paging through
while True:
    # grab a page of sources in the collection
    response = mc_directory.source_list(collection_id=INDIA_NATIONAL_COLLECTION, limit=SOURCES_PER_PAGE, offset=offset)
    # add it to our running list of all the sources in the collection
    sources += response['results']
    # if there is no next page then we're done so bail out
    if response['next'] is None:
        break
    # otherwise setup to fetch the next page of sources
    offset += len(response['results'])
print("India National Collection has {} sources".format(len(sources)))

Development

If you are interested in adding code to this module, first clone the GitHub repository.

Installing

flit install
pre-commit install

Testing

pytest

Distributing a New Version

Run pytest to make sure all the test pass
Update the version number in pyproject.toml
Make a brief note in the CHANGELOG.md about what changes
Commit changes, and tag commit with version number
Push to main

License
- OSI Approved :: Apache Software License
Natural Language
- English
Operating System
- OS Independent
Programming Language

Release files for mediacloud 5.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for mediacloud 5.1.0
File	Size	Uploaded
mediacloud-5.1.0.tar.gz	27.0 kB	May 19, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for mediacloud 5.1.0
File	Interpreter	ABI	Platform	Reset
mediacloud-5.1.0-py3-none-any.whl 30.7 kB May 19, 2026	Python 3	none	any	Details

Total release size: 57.7 kB

Release files / mediacloud-5.1.0.tar.gz

Download URL	mediacloud-5.1.0.tar.gz
Size	27.0 kB
Tags	Source
SHA-256 checksum How to use checksums	`ff103cfca7f941e88cff3bbed96d82ca6b792c832060509d1c00e9e3bc24b049`
BLAKE2b-256 checksum How to use checksums	`a92deb0c376a5bf1b27e0108549d085ff3843c4f9365a7c3ddf305f3e4b4ec86`
Upload date	May 19, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.12`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/mediacloud/api-client
Publishing commit: github.com/mediacloud/api-client/tree/d36ca5d653aa94739e51dc7b52f08fe89b819550

Workflow

Publishing configuration: github.com/mediacloud/api-client/blob/d36ca5d653aa94739e51dc7b52f08fe89b819550/.github/workflows/publish-to-pypi.yml
Publishing logs: github.com/mediacloud/api-client/actions/runs/26099780298/attempts/1

Artifact

Subject: mediacloud-5.1.0.tar.gz
SHA-256 checksum: ff103cfca7f941e88cff3bbed96d82ca6b792c832060509d1c00e9e3bc24b049 Verifying attestations

Release files / mediacloud-5.1.0-py3-none-any.whl

Download URL	mediacloud-5.1.0-py3-none-any.whl
Size	30.7 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`08ea6b382caa6625a2d8c4a51392fbac99b931f0c72c2b5c70c98f44d1fbdfd8`
BLAKE2b-256 checksum How to use checksums	`b1b0ee184b3021a2a47eb2df89974377d2cc37a6c7268dccfe9b1be0bc182e1d`
Upload date	May 19, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.12`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/mediacloud/api-client
Publishing commit: github.com/mediacloud/api-client/tree/d36ca5d653aa94739e51dc7b52f08fe89b819550

Workflow

Publishing configuration: github.com/mediacloud/api-client/blob/d36ca5d653aa94739e51dc7b52f08fe89b819550/.github/workflows/publish-to-pypi.yml
Publishing logs: github.com/mediacloud/api-client/actions/runs/26099780298/attempts/1

Artifact

Subject: mediacloud-5.1.0-py3-none-any.whl
SHA-256 checksum: 08ea6b382caa6625a2d8c4a51392fbac99b931f0c72c2b5c70c98f44d1fbdfd8 Verifying attestations