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.
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 installpre-commit install
Testing
pytest
Distributing a New Version
- Run
pytestto make sure all the test pass - Update the version number in
pyproject.toml - Make a brief note in the
CHANGELOG.mdabout what changes - Commit changes, and tag commit with version number
- Push to main
When client improvements are of great benefit (major new functionality, speed/rate improvements) update web-search API_PYTHON_CLIENT config/default so that library users see a (once a run) warning message that a newer version is available.
Reminder: This library does not currently detect older than expected versions of the server, so if changes here depend on a newer web-search server running, delay release of this library until the new server version is in production, which means a three-step process:
- New server in production
- Release new client
- Update server API_PYTHON_CLIENT to new client version
Doing this out of order with any delay may annoy users!
Release files for mediacloud 5.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| mediacloud-5.2.0.tar.gz | 29.7 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| mediacloud-5.2.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 63.0 kB
Release files / mediacloud-5.2.0.tar.gz
| Download URL | mediacloud-5.2.0.tar.gz |
|---|---|
| Size | 29.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f540c9de5fadf8ed9fbc5218daaaff8213d0df127ae0da1e69d3aa8570126286
|
|
BLAKE2b-256 checksum How to use checksums |
db98b1374a9fddf64d4a960114bc97136186a816a56a7c5450b104e0b29b7c52
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 6, 2026.
Transparency logRelease files / mediacloud-5.2.0-py3-none-any.whl
| Download URL | mediacloud-5.2.0-py3-none-any.whl |
|---|---|
| Size | 33.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d4f1b0fca44f38e11a97d64f785dcb9a8597b544b1b13bd229ee556edc928aa9
|
|
BLAKE2b-256 checksum How to use checksums |
9b5e1b6b0542f3fc7aae41de16aa03e1b3e9d61ca9d2eeae34205ed39ccd2bae
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 6, 2026.
Transparency log
