Mendeley Python SDK¶

Authentication¶

There are three ways to authenticate with the Mendeley Python SDK. Before you start, you’ll need to have registered your application at the developer portal.

from mendeley import Mendeley

# These values should match the ones supplied when registering your application.
mendeley = Mendeley(client_id, client_secret=client_secret, redirect_uri=redirect_uri)

auth = mendeley.start_authorization_code_flow()

# The user needs to visit this URL, and log in to Mendeley.
login_url = auth.get_login_url()

# After logging in, the user will be redirected to a URL, auth_response.
session = auth.authenticate(auth_response)

from mendeley import Mendeley

# These values should match the ones supplied when registering your application.
mendeley = Mendeley(client_id, redirect_uri=redirect_uri)

auth = mendeley.start_implicit_grant_flow()

# The user needs to visit this URL, and log in to Mendeley.
login_url = auth.get_login_url()

# After logging in, the user will be redirected to a URL, auth_response.
session = auth.authenticate(auth_response)

from mendeley import Mendeley

# These values should match the ones supplied when registering your application.
mendeley = Mendeley(client_id, client_secret=client_secret)

auth = mendeley.start_client_credentials_flow()
session = auth.authenticate()

Sessions¶

After authentication, you will have a MendeleySession, which will allow you to access the Mendeley API. The linked resources describe the operations that you can perform, and the objects that you can interact with.

class mendeley.session.MendeleySession¶

Entry point for accessing Mendeley resources.

annotations¶

A :class: Annotations <mendeley.resources.annotations.Annotations> resource for accessing annotations in the logged-in user’s library.

catalog¶

A Catalog resource for accessing the Mendeley catalog.

documents¶

A Documents resource for accessing documents in the logged-in user’s library.

files¶

A Files resource for accessing files in the logged-in user’s library.

groups¶

A Groups resource for accessing groups that the user is a member of.

profiles¶

A Profiles resource for accessing profiles of Mendeley users.

trash¶

A Trash resource for accessing trashed documents in the logged-in user’s library.

Pagination¶

Many collections in the API are spread over multiple pages. Typically, the SDK provides two ways of navigating these collections:

• an iter method, which provides the whole collection as an iterator.
• a list method, which returns the first page of results as a Page. You can use this object to navigate through the other pages.

class mendeley.pagination.Page¶

A page of a collection of objects.

first_page¶

the first Page of the collection.

items¶

a list of items on this page.

last_page¶

the first Page of the collection.

next_page¶

the next Page of the collection, or None if this is the last page.

previous_page¶

the previous Page of the collection, or None if this is the first page.

Examples¶

To print the name of the logged-in user:

print session.profiles.me.display_name

To print the titles of all of the documents in the user’s library:

for document in session.documents.iter():
    print document.title

To print the number of readers of a document by DOI:

print session.catalog.by_identifier(doi='10.1371/journal.pmed.0020124', view='stats').reader_count

Documents¶

class mendeley.resources.documents.Documents¶

Top-level resource for accessing documents. These can be:

• documents for the logged-in user, if retrieved from a MendeleySession.
• documents in a Group.

advanced_search(title=None, author=None, source=None, abstract=None, min_year=None, max_year=None, view=None)¶

Executes an advanced search in the logged-in user’s library, where individual fields can be searched on.

Parameters:	title – Title. author – Author. source – Source. abstract – Abstract. min_year – Minimum year for documents to return. max_year – Maximum year for documents to return. view – the view to get. One of ‘bib’, ‘client’, ‘tags’, ‘all’.
Returns:	a DocumentsSearch resource, from which results can be retrieved.

create(title, type, **kwargs)¶

Creates a new document from metadata.

Parameters:	title – title of the document. type – type of the document. kwargs – other properties of the document. These can be any of the attributes on UserDocument or any of its views.
Returns:	a UserDocument.

create_from_file(path)¶

Creates a new document from a file.

Parameters:	path – path to the file.
Returns:	a UserDocument.

get(id, view=None)¶

Retrieves a document by ID.

Parameters:	id – the ID of the document to get. view – the view to get. One of ‘bib’, ‘client’, ‘tags’, ‘all’.
Returns:	a UserDocument.

iter(page_size=None, view=None, sort=None, order=None, modified_since=None, deleted_since=None)¶

Retrieves documents, as an iterator.

Parameters:

page_size – the number of documents to retrieve at a time. Defaults to 20. view – the view to get. One of ‘bib’, ‘client’, ‘tags’, ‘all’. sort – if specified, sorts documents by the specified field. One of ‘created’, ‘last_modified’, ‘title’. order – if specified in conjunction with ‘sort’, specifies the sort order. One of ‘asc’, ‘desc’. modified_since – if specified, only returns files modified after this timestamp. deleted_since – if specified, only returns the IDs of documents deleted after this timestamp.

Returns:

an iterator of UserDocuments.

list(page_size=None, view=None, sort=None, order=None, modified_since=None, deleted_since=None)¶

Retrieves documents, as a paginated collection.

Parameters:

page_size – the number of documents to return on each page. Defaults to 20. view – the view to get. One of ‘bib’, ‘client’, ‘tags’, ‘all’. sort – if specified, sorts documents by the specified field. One of ‘created’, ‘last_modified’, ‘title’. order – if specified in conjunction with ‘sort’, specifies the sort order. One of ‘asc’, ‘desc’. modified_since – if specified, only returns files modified after this timestamp. deleted_since – if specified, only returns the IDs of documents deleted after this timestamp.

Returns:

a Page of UserDocuments.

search(query, view=None)¶

Searches the logged-in user’s library for documents.

Parameters:	query – the search query to execute. view – the view to get. One of ‘bib’, ‘client’, ‘tags’, ‘all’.
Returns:	a DocumentsSearch resource, from which results can be retrieved.

class mendeley.resources.trash.Trash¶

Top-level resource for accessing trashed documents. These can be:

• trashed documents for the logged-in user, if retrieved from a MendeleySession.
• trashed documents in a Group.

get(id, view=None)¶

Retrieves a trashed document by ID.

Parameters:	id – the ID of the document to get. view – the view to get. One of ‘bib’, ‘client’, ‘tags’, ‘all’.
Returns:	a TrashDocument.

iter(page_size=None, view=None, sort=None, order=None, modified_since=None, deleted_since=None)¶

Retrieves trashed documents, as an iterator.

Parameters:

page_size – the number of documents to retrieve at a time. Defaults to 20. view – the view to get. One of ‘bib’, ‘client’, ‘tags’, ‘all’. sort – if specified, sorts documents by the specified field. One of ‘created’, ‘last_modified’, ‘title’. order – if specified in conjunction with ‘sort’, specifies the sort order. One of ‘asc’, ‘desc’. modified_since – if specified, only returns files modified after this timestamp. deleted_since – if specified, only returns the IDs of documents deleted after this timestamp.

Returns:

an iterator of TrashDocuments.

list(page_size=None, view=None, sort=None, order=None, modified_since=None, deleted_since=None)¶

Retrieves trashed documents, as a paginated collection.

Parameters:

page_size – the number of documents to return on each page. Defaults to 20. view – the view to get. One of ‘bib’, ‘client’, ‘tags’, ‘all’. sort – if specified, sorts documents by the specified field. One of ‘created’, ‘last_modified’, ‘title’. order – if specified in conjunction with ‘sort’, specifies the sort order. One of ‘asc’, ‘desc’. modified_since – if specified, only returns files modified after this timestamp. deleted_since – if specified, only returns the IDs of documents deleted after this timestamp.

Returns:

a Page of TrashDocuments.

Catalog¶

class mendeley.resources.catalog.Catalog¶

Top-level resource for accessing catalog documents.

advanced_search(title=None, author=None, source=None, abstract=None, min_year=None, max_year=None, open_access=None, view=None)¶

Executes an advanced catalog search, where individual fields can be searched on.

Parameters:	title – Title. author – Author. source – Source. abstract – Abstract. min_year – Minimum year for documents to return. max_year – Maximum year for documents to return. open_access – If ‘true’, only returns open access documents. view – the view to get. One of ‘bib’, ‘client’, ‘stats’, ‘all’.
Returns:	a CatalogSearch resource, from which results can be retrieved.

by_identifier(arxiv=None, doi=None, isbn=None, issn=None, pmid=None, scopus=None, filehash=None, view=None)¶

Retrieves a catalog document by an external identifier. Only one identifier may be specified.

Parameters:	arxiv – ArXiV ID. doi – DOI. isbn – ISBN. issn – ISSN. pmid – PubMed ID. scopus – Scopus ID (EID). filehash – SHA-1 filehash. view – the view to get. One of ‘bib’, ‘client’, ‘stats’, ‘all’.
Returns:	a CatalogDocument.

get(id, view=None)¶

Retrieves a catalog document by ID.

Parameters:	id – the ID of the document to get. view – the view to get. One of ‘bib’, ‘client’, ‘stats’, ‘all’.
Returns:	a CatalogDocument.

lookup(arxiv=None, doi=None, pmid=None, filehash=None, title=None, authors=None, year=None, source=None, view=None)¶

Finds the closest matching catalog document to a supplied set of metadata.

Parameters:	arxiv – ArXiV ID. doi – DOI. pmid – PubMed ID. filehash – SHA-1 filehash. title – Title. authors – Authors. year – Year. source – Source. view – the view to get. One of ‘bib’, ‘client’, ‘stats’, ‘all’.
Returns:	a CatalogDocument.

search(query, view=None)¶

Searches the catalog for documents.

Parameters:	query – the search query to execute. view – the view to get. One of ‘bib’, ‘client’, ‘stats’, ‘all’.
Returns:	a CatalogSearch resource, from which results can be retrieved.

class mendeley.resources.catalog.CatalogSearch¶

Resource for accessing the results of a catalog search.

iter(page_size=None)¶

Retrieves search results, as an iterator.

Parameters:	page_size – the number of search results to retrieve at a time. Defaults to 20.
Returns:	an iterator of CatalogDocuments.

list(page_size=None)¶

Retrieves search results, as a paginated collection.

Parameters:	page_size – the number of search results to return on each page. Defaults to 20.
Returns:	a Page of CatalogDocuments.

Files¶

class mendeley.resources.files.Files¶

Top-level resource for accessing files. These can be:

• files for the logged-in user, if retrieved from a MendeleySession.
• files attached to a CatalogDocument.
• files attached to a UserDocument.
• files in a Group.

iter(page_size=None, added_since=None, deleted_since=None)¶

Retrieves files, as an iterator.

Parameters:	page_size – the number of files to retrieve at a time. Defaults to 20. added_since – if specified, only returns files added after this timestamp. deleted_since – if specified, only returns the IDs of files deleted after this timestamp.
Returns:	an iterator of Files.

list(page_size=None, added_since=None, deleted_since=None)¶

Retrieves files, as a paginated collection.

Parameters:	page_size – the number of files to return on each page. Defaults to 20. added_since – if specified, only returns files added after this timestamp. deleted_since – if specified, only returns the IDs of files deleted after this timestamp.
Returns:	a Page of Files.

Groups¶

class mendeley.resources.groups.Groups¶

Top-level resource for accessing groups.

get(id)¶

Retrieves a group by ID.

Parameters:	id – the ID of the group to get.
Returns:	a Group.

iter(page_size=None)¶

Retrieves groups that the logged-in user is a member of, as an iterator.

Parameters:	page_size – the number of groups to retrieve at a time. Defaults to 20.
Returns:	an iterator of Groups.

list(page_size=None)¶

Retrieves groups that the logged-in user is a member of, as a paginated collection.

Parameters:	page_size – the number of groups to return on each page. Defaults to 20.
Returns:	a Page of Groups.

class mendeley.resources.groups.GroupMembers¶

Resource for accessing members of a group.

iter(page_size=None)¶

Retrieves members of the group, as an iterator.

Parameters:	page_size – the number of members to retrieve at a time. Defaults to 20.
Returns:	an iterator of GroupMembers.

list(page_size=None)¶

Retrieves members of the group, as a paginated collection.

Parameters:	page_size – the number of members to return on each page. Defaults to 20.
Returns:	a Page of GroupMembers.

Profiles¶

class mendeley.resources.profiles.Profiles¶

Top-level resource for accessing profiles.

get(id)¶

Retrieves a profile by ID.

Parameters:	id – the ID of the profile to get.
Returns:	a Profile.

me¶

The Profile of the logged-in user.

Annotations¶

class mendeley.resources.annotations.Annotations¶

Top-level resource for accessing annotations.

get(id)¶

Retrieves an annotation by ID.

Parameters:	id – the ID of the annotation to get.
Returns:	a Annotation.

iter(page_size=None, modified_since=None, deleted_since=None)¶

Retrieves annotations that the logged-in user is a member of, as an iterator.

Parameters:	page_size – the number of annotations to retrieve at a time. Defaults to 20. modified_since – if specified, only returns annotations modified after this timestamp. deleted_since – if specified, only returns the annotations deleted after this timestamp.
Returns:	an iterator of Annotations.

list(page_size=None, modified_since=None, deleted_since=None)¶

Retrieves annotations as a paginated collection.

Parameters:	page_size – the number of annotations to return on each page. Defaults to 20. modified_since – if specified, only returns annotations modified after this timestamp. deleted_since – if specified, only returns annotations deleted after this timestamp.
Returns:	a Page of

Annotations.

User documents¶

Catalog documents¶

Profiles¶

class mendeley.models.profiles.Profile¶

A Mendeley profile.

id¶

first_name¶

last_name¶

display_name¶

email¶

link¶

research_interests¶

academic_status¶

verified¶

user_type¶

created¶

an Arrow object.

discipline¶

a Discipline.

education¶

a list of Education objects.

employment¶

a list of Employment objects.

location¶

a Location.

photo¶

a Photo.

Groups¶

class mendeley.models.groups.Group¶

A Mendeley group.

id¶

name¶

description¶

disciplines¶

tags¶

webpage¶

link¶

access_level¶

role¶

created¶

an Arrow object.

documents¶

a Documents resource, from which UserDocuments can be retrieved.

files¶

a Files resource, from which Files can be retrieved.

owner¶

a Profile.

photo¶

a Photo.

trash¶

a Trash resource, from which TrashDocuments can be retrieved.

class mendeley.models.groups.GroupMember¶

A member of a Mendeley group.

id¶

role¶

first_name¶

last_name¶

display_name¶

email¶

link¶

research_interests¶

academic_status¶

verified¶

user_type¶

created¶

an Arrow object.

discipline¶

a Discipline.

education¶

a list of Education objects.

employment¶

a list of Employment objects.

joined¶

an Arrow object.

location¶

a Location.

photo¶

a Photo.

Files¶

class mendeley.models.files.File¶

A file attached to a document.

id¶

size¶

file_name¶

mime_type¶

filehash¶

download_url¶

add_highlight(bounding_boxes, color)¶

Adds a highlight to this file.

Parameters:	bounding_boxes – the area the highlight covers on the file. color – the color of the highlight.
Returns:	a Annotation.

add_sticky_note(text, x_position, y_position, page_number)¶

Adds a sticky note to this file.

Parameters:	text – the text of the sticky_note. x_position – the x position on the file of the sticky_note. y_position – the y position on the file of the stick_note. page_number – the page_number on the file of the sticky_note.
Returns:	a Annotation.

delete()¶

Deletes the file.

document(view=None)¶

Parameters:	view – document view to return.
Returns:	a UserDocument or CatalogDocument, depending on which the document is attached to.

download(directory)¶

Downloads the file.

Parameters:	directory – the directory to download the file to. This must exist.
Returns:	the path to the downloaded file.

download_url¶

the URL at which the file can be downloaded. This is only valid for a short time, so should not be cached.

Annotations¶

class mendeley.models.annotations.Annotation¶

An annotation attached to a document or a file.

id¶

type¶

text¶

privacy_level¶

color¶

a Color.

created¶

an Arrow object.

delete()¶

Permanently deletes this annotation.

document(view=None)¶

Parameters:	view – document view to return.
Returns:	a UserDocument

last_modified¶

an Arrow object.

positions¶

a list of BoundingBox.

profile¶

a Profile.

update(**kwargs)¶

Updates this annotation.

Common objects¶

class mendeley.models.common.Discipline¶

The discipline of a Profile.

name¶

subdisciplines¶

class mendeley.models.common.Education¶

Education details, associated with a Profile.

institution¶

degree¶

website¶

end_date¶

an Arrow object.

start_date¶

an Arrow object.

class mendeley.models.common.Employment¶

Employment details, associated with a Profile.

institution¶

position¶

website¶

classes¶

end_date¶

an Arrow object.

start_date¶

an Arrow object.

class mendeley.models.common.Location¶

A location, associated with a Profile.

latitude¶

longitude¶

name¶

class mendeley.models.common.Person¶

A person, associated with a Document, as either an author or an editor.

first_name¶

last_name¶

static create(first_name, last_name)¶

Creates a person object, to be used when creating or updating a Document.

Parameters:	first_name – last_name –
Returns:	a Person.

class mendeley.models.common.Photo¶

A photo, associated with a Profile or Group.

original¶

standard¶

square¶