Mendeley Python SDK

The Mendeley Python SDK provides access to the Mendeley API. For more information on the API and its capabilities, see the developer portal.

Installation

Install from PyPI using pip, a package manager for Python.

pip install mendeley

Compatibility

The SDK has been tested with Python 2.7 and 3.4.

Sample applications

There are two sample applications that illustrate how to use the SDK:

Contents

Using the 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.

Authorization code flow

This flow is recommended for applications that have access to secure, private storage, such as web applications deployed on a server.

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)
Implicit grant flow

This flow is recommended for applications running in environments that do not provide secure storage.

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)
Client credentials flow

This flow does not require the user to log in. However, it only provides access to a limited set of resources (the read-only Mendeley Catalog of crowd sourced documents).

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.

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

Resources

This page details the top-level resources that are available from a Mendeley session.

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.

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.

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:

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.

Models

This page details the various model objects in the Mendeley Python SDK.

User documents

Documents
class mendeley.models.documents.UserDocument

Base class for user documents.

id
title
type
source
year
identifiers
keywords
abstract
add_note(text)

Adds a note to this document.

Parameters:text – the text of the note to add.
Returns:a Annotation.
attach_file(path)

Attaches a file to this document.

Parameters:path – the path of the file to attach.
Returns:a File.
authors

a list of Persons.

created

an Arrow object.

delete()

Permanently deletes this document.

files

a Files resource, from which Files can be retrieved.

group

a Group.

last_modified

an Arrow object.

move_to_trash()

Moves this document to the trash.

Returns:a TrashDocument.
profile

a Profile.

update(**kwargs)

Updates this document.

Parameters:kwargs – updated field values. Only the values supplied will be modified.
Returns:the updated document.
class mendeley.models.documents.TrashDocument

Base class for trashed documents.

id
title
type
source
year
identifiers
keywords
abstract
authors

a list of Persons.

created

an Arrow object.

delete()

Permanently deletes this document.

files

a Files resource, from which Files can be retrieved.

group

a Group.

last_modified

an Arrow object.

profile

a Profile.

restore()

Restores this document from the trash.

Returns:a UserDocument.
Views

The following views are available on UserDocuments and TrashDocuments.

class mendeley.models.documents.UserBibView

Additional fields returned when getting a UserDocument or TrashDocument with view=’bib’ or ‘all’.

pages
volume
issue
websites
month
publisher
day
city
edition
institution
series
chapter
revision
accessed

an Arrow object.

editors

a list of Persons.

class mendeley.models.documents.UserClientView

Additional fields returned when getting a UserDocument or TrashDocument with view=’client’ or ‘all’.

file_attached
read
starred
authored
confirmed
hidden
class mendeley.models.documents.UserTagsView

Additional fields returned when getting a UserDocument or TrashDocument with view=’tags’ or ‘all’.

tags

Catalog documents

Documents
class mendeley.models.catalog.CatalogDocument

Base class for catalog documents.

id
title
type
source
year
identifiers
keywords
abstract
authors

a list of Persons.

files

a Files resource, from which Files can be retrieved.

Views

The following views are available on CatalogDocuments.

class mendeley.models.catalog.CatalogBibView

Additional fields returned when getting a CatalogDocument with view=’bib’ or ‘all’.

pages
volume
issue
websites
month
publisher
day
city
edition
institution
series
chapter
revision
editors

a list of Persons.

class mendeley.models.catalog.CatalogClientView

Additional fields returned when getting a CatalogDocument with view=’client’ or ‘all’.

file_attached
class mendeley.models.catalog.CatalogStatsView

Additional fields returned when getting a CatalogDocument with view=’stats’ or ‘all’.

reader_count
reader_count_by_academic_status
reader_count_by_subdiscipline
reader_count_by_country

Profiles

class mendeley.models.profiles.Profile

A Mendeley profile.

id
first_name
last_name
display_name
email
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
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
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