Documentation¶
Main Module¶
It’s the interface module of the package. Developers will start interacting with the API/package using Medium Class object via different functions provided in it.
- class medium_api.medium.Medium(rapidapi_key: str, base_url: str = 'medium2.p.rapidapi.com', calls: int = 0)[source]¶
Bases:
object
Main Medium API Class to access everything
Typical usage example:
from medium_api import Medium
medium = Medium('YOUR_RAPIDAPI_KEY')
- Parameters:
rapidapi_key (str) –
A secret alphanumeric string value. To get your RapidAPI key, please go to the following URL, register an account and subscribe to Medium API (by Nishu Jain).
https://rapidapi.com/nishujain199719-vgIfuFHZxVZ/api/medium2
base_url (str, optional) – It’s the base URL of the API that is used by all the other endpoints. Currently, it is set to the RapidAPI’s domain (medium2.p.rapidapi.com). May change in the future according to where it’s listed.
calls (int, optional) –
It’s an integer value for keeping track of all the API calls made by the Medium Class Object. Initially, it is set to 0. At the end of program, you can see the number of calls like this:
print(medium.calls)
- Returns:
A Medium Class Object for the given RAPIDAPI_KEY. It can be used to access all the other functions such as: user, article, publication, topfeeds, top_writers, etc …
- Return type:
Note
See https://docs.rapidapi.com/docs/keys to learn more about RapidAPI keys.
- user(username: str | None = None, user_id: str | None = None, save_info: bool = True)[source]¶
For getting the Medium User Object
Typical usage example:
nishu = medium.user(username="nishu-jain")
- Parameters:
username (str, optional) –
It’s your unique Medium username that you can find in the subdomain or at the end of the profile page URL as shown below.
username
.medium.commedium.com/@
username
It’s optional only if you’ve already provided the user_id.
user_id (str, optional) – It’s your unique alphanumeric Medium ID that cannot be changed. The User object is initialized using this only. It’s optional only if you’ve already provided the username.
save_info (bool, optional) – If False, creates an empty User object which needs to be filled using
user.save_info()
method later. (Default is True)
- Returns:
Medium API’s User Object (medium_api.user.User) that can be used to access all the properties and methods associated to the given Medium user.
- Return type:
Note
You have to provide either username or user_id to get the User object. You cannot omit both.
- article(article_id: str, save_info: bool = True)[source]¶
For getting the Medium Article Object
Typical usage example:
article = medium.article(article_id = "562c5821b5f0")
- Parameters:
article_id (str) –
It’s the unique hash at the end of every Medium Article. You can see it at the end of URL as shown below:
save_info (bool, optional) – If False, creates an empty Article object which needs to be filled using
article.save_info()
method later. (Default is True)
- Returns:
Medium API Article Object (medium_api.article.Article) that can be used to access all the properties and methods related to a Medium Article.
- Return type:
- publication(publication_slug: str | None = None, publication_id: str | None = None, save_info: bool = True)[source]¶
For getting the Medium Publication Object
Typical usage example:
publication = medium.publication(publication_slug = "towards-artificial-intelligence")
publication = medium.publication(publication_id = "98111c9905da")
- Parameters:
publication_slug (str, optional) – It’s a lowercased hyphen-separated unique string alloted to each Medium Publication. It’s optional only if you’ve already provided the publication_id.
publication_id (str, optional) – It’s the unique hash id of a Medium Publication. It’s optional only if you’ve already provided the publication_slug.
save_info (bool, optional) – If False, creates an empty Publication object which needs to be filled using
publication.save_info()
method later. (Default is True)
- Returns:
Medium API Publication Object (medium_api.publication.Publication) that can be used to access all the properties and methods related to a Medium Publication.
- Return type:
Note
You have to provide either publication_slug or publication_id to get the Publication object. You cannot omit both.
- top_writers(topic_slug: str)[source]¶
For getting the Medium’s TopWriters Object
Typical usage example:
top_writers = medium.top_writers(topic_slug = "artificial-intelligence")
- Parameters:
topic_slug (str) – It’s a string (smallcase, hyphen-separated) which specifies a category/niche as classified by the Medium Platform.
- Returns:
Medium API TopWriters Object (medium_api.top_writers.TopWriters) that can be used to access all the properties and methods related to Medium’s Top Writers for the give topic_slug.
- Return type:
- latestposts(topic_slug: str)[source]¶
For getting the Medium’s LatestPosts Object
Typical usage example:
latestposts = medium.latestposts(topic_slug = "artificial-intelligence")
- Parameters:
topic_slug (str) – It’s a string (smallcase, hyphen-separated) which specifies a category/niche as classified by the Medium Platform.
- Returns:
Medium API LatestPosts Object (medium_api.latestposts.LatestPosts) that can be used to access all the properties and methods related to Medium’s LatestPosts within the given topic.
- Return type:
- topfeeds(tag: str, mode: str)[source]¶
For getting the Medium’s TopFeeds Object
Typical usage example:
topfeeds = medium.topfeeds(tag="blockchain", mode="new")
- Parameters:
tag (str) – It’s a string (smallcase, hyphen-separated) which specifies a category/niche as classified by the Medium Platform.
mode (str) –
There are 6 modes as follows:
hot
: For getting trending articlesnew
: For getting latest articlestop_year
: For getting best articles of the yeartop_month
: For getting best articles of the monthtop_week
: For getting best articles of the weektop_all_time
: For getting best article of all time
- Returns:
Medium API TopFeeds Object (medium_api.topfeeds.TopFeeds) that can be used to access all the properties and methods, for given tag and mode.
- Return type:
For getting the list of related tags
Typical usage example:
related_tags = medium.related_tag(given_tag="blockchain")
- Parameters:
given_tag (str) – It’s a string (smallcase, hyphen-separated) which specifies a category/niche as classified by the Medium Platform.
- Returns:
List of Related Tags (strings).
- Return type:
list[str]
- fetch_articles(articles: list, content: bool = False)[source]¶
To quickly fetch articles (info and content) using multithreading
Typical usage example:
medium.fetch_articles(latestposts.articles)
medium.fetch_articles(user.articles)
medium.fetch_articles(list_of_articles_obj)
- Parameters:
articles (list[Article]) – List of (empty) Article objects to fill information (and content) into it.
content (bool, optional) – Set it to True if you want to fetch the content of the article as well. Otherwise, default is False
- Returns:
This method doesn’t return anything since it fills the values in the passed list of Article(s) objects itself.
- Return type:
None
- fetch_users(users: list)[source]¶
To quickly fetch users info using multithreading
Typical usage example:
medium.fetch_users(top_writers.users)
medium.fetch_users(list_of_users_obj)
- Parameters:
users (list[User]) – List of (empty) User objects to fill information into it.
- Returns:
This method doesn’t return anything since it fills the values into the passed list of User(s) objects itself.
- Return type:
None
- extract_article_id(article_url: str)[source]¶
To get article_id from the Article’s URL
Usage example:
article_id = medium.get_article_id("https://nishu-jain.medium.com/about-me-nishu-jain-562c5821b5f0")
- Parameters:
article_url (str) – URL as string type
- Returns:
Returns article_id as string for valid URL, else returns None.
- Return type:
str
Classes¶
User class¶
- class medium_api._user.User(user_id, get_resp, fetch_articles, fetch_users, save_info=False)[source]¶
User Class
With User object, you can use the following properties and methods:
user._id
user.info
user.article_ids
user.articles
user.top_article_ids
user.top_articles
user.following_ids
user.following
user.followers_ids
user.followers
user.interests
user.articles_as_json
user.save_info()
user.fetch_articles()
user.fetch_top_articles()
Note
User class is NOT intended to be used directly by importing. See
medium_api.medium.Medium.user
.- property info¶
To get the user related information
- Returns:
A dictionary object containing fullname, username, followers, bio, twitter_username, image_url, etc …
- Return type:
dict
- property article_ids¶
To get a full list of article_ids
- Returns:
A list of article_ids (str) written by the user
- Return type:
list[str]
- property top_article_ids¶
To get a list of top 10 article_ids
- Returns:
A list of article_ids (str) of the top 10 posts on the user’s profile. (Usually, in chronological order)
- Return type:
list[str]
- property interests¶
To get a list of tags that the user follows.
- Returns:
A list of tags (str) followed by the user.
- Return type:
list[str]
- property following_ids¶
To get a list of user_ids of user’s followings
- Returns:
A list of user_ids (str) of the user’s followings.
- Return type:
list[str]
- property followers_ids¶
To get a list of user_ids of user’s followers
- Returns:
A list of user_ids (str) of the user’s followers.
- Return type:
list[str]
- property following¶
To get a full list of following User objects
- Returns:
A list of User objects followed by the given user
- Return type:
list[User]
- property followers¶
To get a full list of followers User objects
- Returns:
A list of User objects of followers
- Return type:
list[User]
- fetch_following()[source]¶
To user’s followings information
- Returns:
All the fetched information will be access via top_writers.users.
user.following[0].fullname
user.following[1].bio
- Return type:
None
- fetch_followers()[source]¶
To user’s followers information
- Returns:
All the fetched information will be access via top_writers.users.
user.followers[0].fullname
user.followers[1].bio
- Return type:
None
- property articles¶
To get a full list of user-written Article objects
- Returns:
A list of Article objects written by the user
- Return type:
list[Article]
- property top_articles¶
To get a list of top 10 articles
- Returns:
A list of Article objects of the top 10 posts on the user’s profile. (Usually, in chronological order)
- Return type:
list[Article]
- property articles_as_json¶
To get a list of JSON objects containing user info
- Returns:
A list of JSON objects containing information related to all the posts on the user’s profile.
- Return type:
list[dict]
- save_info()[source]¶
Saves the information related to the user
Note
Only after running
user.save_info()
you can use the following variables:user.fullname
user.username
user.followers_count
user.following_count
user.bio
user.twitter_username
user.is_writer_program_enrolled
user.is_suspended
user.allow_notes
user.medium_member_at
user.top_writer_in
user.image_url
- fetch_articles(content=False)[source]¶
To fetch all the user-written articles information and content
- Parameters:
content (bool, optional) – Set it to True if you want to fetch the textual content of the article as well. Otherwise, default is False.
- Returns:
All the fetched information will be access via user.articles.
user.articles[0].title
user.articles[1].claps
- Return type:
None
- fetch_top_articles(content=False)[source]¶
To fetch top 10 user-written top articles information and content
- Parameters:
content (bool, optional) – Set it to True if you want to fetch the textual content of the article as well. Otherwise, default is False.
- Returns:
All the fetched information will be access via user.articles.
user.top_articles[0].title
user.top_articles[1].claps
- Return type:
None
Article class¶
- class medium_api._article.Article(article_id, get_resp, fetch_articles, fetch_users, save_info=False)[source]¶
Article Class
With Article object, you can use the following properties and methods:
article._id
article.info
article.responses
article.is_self_published
article.content
article.markdown
article.json
article.save_info()
article.save_content()
article.save_markdown()
article.fetch_responses()
Note
Article class is NOT intended to be used directly by importing. See
medium_api.medium.Medium.article
.- save_info()[source]¶
Saves the information related to the article
Note
Only after running
article.save_info()
you can use the following variables:article.title
article.subtitle
article.claps
article.author
article.url
article.published_at
article.publication_id
article.tags
article.topics
article.last_modified_at
article.reading_time
article.word_count
article.responses_count
article.voters
article.lang
article.is_series
article.is_locked
article.image_url
article.publication
- save_content()[source]¶
Saves the textual content of the article
Can be accessed later using
article.content
- Returns:
None
- save_markdown()[source]¶
Saves the markdown of the article
Can be accessed later using
article.markdown
- Returns:
None
- property info¶
To get the articles information
- Returns:
Returns a dictionary object containing title, subtitle, claps, voters, author, publication_id, word_count, etc … (excluding content)
- Return type:
dict
- property response_ids¶
To get the list of ids of responses (comments) on the article
- Returns:
Returns a list of response_ids.
- Return type:
list
- property responses¶
To get the list of responses (Article Objects)
- Returns:
Returns a list of Article Objects.
- Return type:
list[Article]
- fetch_responses(content=True)[source]¶
To fetch all the responses information and content on an article.
- Parameters:
content (bool, optional) – Set it to True if you want to fetch the textual content of the article as well. Otherwise, default is False.
- Returns:
All the fetched information will be access via user.articles.
article.responses[0].content
article.responses[1].claps
- Return type:
None
- property is_self_published¶
To check if the article is self-published or not
- Returns:
Returns True if article is self-published, else False if article is published under a Medium Publication.
- Return type:
bool
- property content¶
To get the textual content of the article
- Returns:
A single string containing kicker, title, subtitle, paragraphs, image captions, listicles, etc … within an article
- Return type:
str
- property markdown¶
To get the Markdown of the Medium Article
- Returns:
A single string containing kicker, title, subtitle, paragraphs, images, listicles, etc … within an article, in the markdown format
- Return type:
str
- property json¶
To get the articles information in JSON format
- Returns:
Returns a JSON object containing article info, content, and markdown if already fetched. Else, returns an empty object.
- Return type:
dict
Publication class¶
- class medium_api._publication.Publication(publication_id, get_resp, fetch_articles, fetch_users, save_info=False)[source]¶
Publication Class
With Publication object, you can use the following properties and methods:
publication._id
publication.info
publication.articles
publication.save_info()
publication.fetch_articles()
Note
Publication class is NOT intended to be used directly by importing. See
medium_api.medium.Medium.publication
.- property info¶
To get the publication related information
- Returns:
A dictionary object containing name, slug, followers, description, tagline, url, twitter_username, tags, etc …
- Return type:
dict
- save_info()[source]¶
Saves the information related to the publication
Note
Only after running
publication.save_info()
you can use the following variables:publication.name
publication.description
publication.url
publication.tagline
publication.followers
publication.slug
publication.tags
publication.domain
publication.creator
publication.editors
publication.twitter_username
publication.instagram_username
publication.facebook_pagename
- articles_from_ids(article_ids)[source]¶
A generic function to get Article Objects from article_ids (list).
- Parameters:
article_ids (list[str]) – List of
article_ids
(string)- Returns:
Returns a list of Article Objects.
- Return type:
list[Article]
- get_articles_between(_from=None, _to=None)[source]¶
To get publication articles within a datetime range.
Example usage:
publication.get_articles_between(_from=datetime.now(), _to=datetime.now() - timedelta(days=15))
- Parameters:
_from (datetime.datetime) – Starting date of the interval
_to (datetime.datetime) – Ending date of the interval
- Returns:
Returns a list of Article Objects (publication articles).
- Return type:
list[Article]
Note
If the
_to
parameter is not provided, then the function will return recent 25 articles from the given date (in_from
parameter)If the
_from
parameter is not provided, then the function will take current datetime value (datetime.now()
)If both the parameters,
_from
and_to
, are not provided, then the function will return top recent 25 articles from the current datetime.
LatestPosts class¶
- class medium_api._latestposts.LatestPosts(topic_slug, get_resp, fetch_articles, fetch_users)[source]¶
LatestPosts Class
With LatestPosts object, you can use the following properties and methods:
latestposts.ids
latestposts.articles
latestposts.fetch_articles()
Note
LatestPosts class is NOT intended to be used directly by importing. See
medium_api.medium.Medium.latestposts
.- property ids¶
To get the article_ids of the latestposts
- Returns:
Returns a list of article ids (str).
- Return type:
list[str]
- property articles¶
To get a list of Article objects of the latestposts
- Returns:
Returns a list of Article objects.
- Return type:
list[Article]
- fetch_articles(content=False)[source]¶
To fetch all the latestposts articles information (multithreading)
- Parameters:
content (bool, optional) – Set it to True if you want to fetch the textual content of the article as well. Otherwise, default is False.
- Returns:
All the fetched information will be access via latestposts.articles.
latestposts.articles[0].title
latestposts.articles[1].claps
- Return type:
None
TopWriters class¶
- class medium_api._top_writers.TopWriters(topic_slug, get_resp, fetch_users, fetch_articles)[source]¶
TopWriters Class
With TopWriters object, you can use the following properties and methods:
top_writers.ids
top_writers.users
top_writers.fetch_users()
Note
TopWriters class is NOT intended to be used directly by importing. See
medium_api.medium.Medium.top_writers
.- property ids¶
To get a list of top writer’s user_ids
- Returns:
A list of user_ids of the top writers for the given topic/niche.
- Return type:
list[str]
TopFeeds class¶
- class medium_api._topfeeds.TopFeeds(tag, mode, get_resp, fetch_articles, fetch_users)[source]¶
TopFeeds Class
With TopFeeds object, you can use the following properties and methods:
topfeeds.ids
topfeeds.articles
topfeeds.fetch_articles()
Note
TopFeeds class is NOT intended to be used directly by importing. See
medium_api.medium.Medium.topfeeds
.- property ids¶
To get a list of topfeeds article_ids
- Returns:
A list of article_ids (str) from the topfeeds for the given tag and mode.
- Return type:
list[str]
- property articles¶
To get a list of topfeeds Article objects
- Returns:
A list of Article objects from the topfeeds for the given tag and mode.
- Return type:
list[Article]
- fetch_articles(content=False)[source]¶
To fetch all the topfeeds articles information (multithreading)
- Parameters:
content (bool, optional) – Set it to True if you want to fetch the textual content of the article as well. Otherwise, default is False.
- Returns:
All the fetched information will be access via topfeeds.articles.
topfeeds.articles[0].title
topfeeds.articles[1].claps
- Return type:
None