In sbalci/lens2r: R Interface to the Lens API

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

library(lens2r)
# Load dependencies
library(httr)
library(jsonlite)

Usage

https://cran.r-project.org/web/packages/httr/vignettes/quickstart.html

token <- Sys.getenv("LENS_TOKEN")

lens_get <- httr::GET(
  "https://api.lens.org/scholarly/usage",
  httr::add_headers(.headers =
                      c("Authorization" = token,
                        "Content-Type" = "application/json")
                    )
)

lens_get
# View(lens_get)

lens_get[["url"]]

lens_get[["status_code"]]

lens_get[["headers"]]

lens_get[["headers"]][["date"]]

lens_get[["headers"]][["content-type"]]

lens_get[["headers"]][["content-encoding"]]

lens_get[["headers"]][["vary"]]

lens_get[["all_headers"]]

lens_get[["all_headers"]][[1]]

lens_get[["all_headers"]][[1]][["status"]]

lens_get[["all_headers"]][[1]][["version"]]

lens_get[["all_headers"]][[1]][["headers"]]

lens_get[["all_headers"]][[1]][["headers"]][["date"]]

lens_get[["all_headers"]][[1]][["headers"]][["content-type"]]

lens_get[["all_headers"]][[1]][["headers"]][["content-encoding"]]

lens_get[["all_headers"]][[1]][["headers"]][["vary"]]

lens_get[["cookies"]]

lens_get[["cookies"]][["domain"]]

lens_get[["cookies"]][["flag"]]

lens_get[["cookies"]][["path"]]

lens_get[["cookies"]][["secure"]]

lens_get[["cookies"]][["expiration"]]

lens_get[["cookies"]][["name"]]

lens_get[["cookies"]][["value"]]

lens_get[["content"]]

lens_get[["date"]]

lens_get[["times"]]

lens_get[["times"]][["redirect"]]

lens_get[["times"]][["namelookup"]]

lens_get[["times"]][["connect"]]

lens_get[["times"]][["pretransfer"]]

lens_get[["times"]][["starttransfer"]]

lens_get[["times"]][["total"]]

lens_get[["request"]]

lens_get[["request"]][["method"]]

lens_get[["request"]][["url"]]

---

Get Scholarly Data

Code Samples - R

require(httr)
getScholarlyData <- function(token, query){
    url <- 'https://api.lens.org/scholarly/search'
    headers <- c('Authorization' = token, 'Content-Type' = 'application/json')
    httr::POST(url = url, add_headers(.headers=headers), body = query)
}
token <- 'your-access-token'
request <- '{
    "query": {
        "match_phrase": {
            "author.affiliation.name": "Harvard University"
        }
    },
    "size": 1,
    "sort": [{
        "year_published": "desc"
    }]
}'
data <- getScholarlyData(token, request)
content(data, "text")

get_scholarly_data.R

library(lens2r)

request <- '{
    "query": {
        "match_phrase": {
            "author.affiliation.name": "Harvard University"
        }
    },
    "size": 1,
    "sort": [{
        "year_published": "desc"
    }]
}'


data <- lens2r::get_scholarly_data(query = request)

output_content <- httr::content(data, "text")

output_flatten <- jsonlite::fromJSON(output_content, flatten = TRUE)

output_flatten_data <- output_flatten$data

output_flatten_data

output_flatten <- as.data.frame(output_flatten)

output_flatten

---

Get Collection Data

https://www.lens.org/lens/scholar/search/results?collectionId=170675

token <- Sys.getenv("LENS_TOKEN")

collection_lens <- httr::GET(
  "https://api.lens.org/collections/170675",
  httr::add_headers(.headers =
                      c("Authorization" = token,
                        "Content-Type" = "application/json")
                    )
)

collection_lens
# View(collection_lens)

collection_lens[["url"]]
collection_lens[["status_code"]]
collection_lens[["headers"]]
collection_lens[["headers"]][["date"]]
collection_lens[["headers"]][["content-type"]]
collection_lens[["headers"]][["x-rate-limit-reset-date"]]
collection_lens[["headers"]][["x-rate-limit-remaining-request-per-month"]]
collection_lens[["headers"]][["x-rate-limit-remaining-record-per-month"]]
collection_lens[["headers"]][["x-rate-limit-remaining-request-per-minute"]]
collection_lens[["headers"]][["x-result-time"]]
collection_lens[["headers"]][["content-encoding"]]
collection_lens[["headers"]][["vary"]]
collection_lens[["all_headers"]]
collection_lens[["all_headers"]][[1]]
collection_lens[["all_headers"]][[1]][["status"]]
collection_lens[["all_headers"]][[1]][["version"]]
collection_lens[["all_headers"]][[1]][["headers"]]
collection_lens[["all_headers"]][[1]][["headers"]][["date"]]
collection_lens[["all_headers"]][[1]][["headers"]][["content-type"]]
collection_lens[["all_headers"]][[1]][["headers"]][["x-rate-limit-reset-date"]]
collection_lens[["all_headers"]][[1]][["headers"]][["x-rate-limit-remaining-request-per-month"]]
collection_lens[["all_headers"]][[1]][["headers"]][["x-rate-limit-remaining-record-per-month"]]
collection_lens[["all_headers"]][[1]][["headers"]][["x-rate-limit-remaining-request-per-minute"]]
collection_lens[["all_headers"]][[1]][["headers"]][["x-result-time"]]
collection_lens[["all_headers"]][[1]][["headers"]][["content-encoding"]]
collection_lens[["all_headers"]][[1]][["headers"]][["vary"]]
collection_lens[["cookies"]]
collection_lens[["cookies"]][["domain"]]
collection_lens[["cookies"]][["flag"]]
collection_lens[["cookies"]][["path"]]
collection_lens[["cookies"]][["secure"]]
collection_lens[["cookies"]][["expiration"]]
collection_lens[["cookies"]][["name"]]
collection_lens[["cookies"]][["value"]]
collection_lens[["content"]]
collection_lens[["date"]]
collection_lens[["times"]]
collection_lens[["times"]][["redirect"]]
collection_lens[["times"]][["namelookup"]]
collection_lens[["times"]][["connect"]]
collection_lens[["times"]][["pretransfer"]]
collection_lens[["times"]][["starttransfer"]]
collection_lens[["times"]][["total"]]
collection_lens[["request"]]
collection_lens[["request"]][["method"]]
collection_lens[["request"]][["url"]]
collection_lens[["request"]][["headers"]]
collection_lens[["request"]][["headers"]][["Accept"]]
# collection_lens[["request"]][["headers"]][["Authorization"]]
collection_lens[["request"]][["headers"]][["Content-Type"]]
collection_lens[["request"]][["fields"]]
collection_lens[["request"]][["options"]]
collection_lens[["request"]][["options"]][["useragent"]]
collection_lens[["request"]][["options"]][["httpget"]]
collection_lens[["request"]][["auth_token"]]
collection_lens[["request"]][["output"]]
collection_lens[["handle"]]

output_collection_lens <- httr::content(collection_lens, "text")

output_collection_flatten <- jsonlite::fromJSON(output_collection_lens,
                                     flatten = TRUE)

output_collection_flatten_data <- output_collection_flatten$data

output_collection_flatten_data

output_collection_flatten <- as.data.frame(output_collection_flatten)

output_collection_flatten

---

Examples

Find 20 records from offset 10 that match provided query

request <- 
'{
  "query": "X-ray analysis of protein crystals",
  "size": 20,
  "from": 10
}'


data <- lens2r::get_scholarly_data(query = request)

output_content <- httr::content(data, "text")

data <- lens2r::get_scholarly_df(query = request)

data_json <- lens2r::get_scholarly_df(query = request, output = "json")

Get the patent citations, scholarly citations and references for a list of scholarly works using the lens_id

request <- 
'{
  "query": {
    "terms":{
      "lens_id": ["017-767-306-508-482", "017-624-265-921-255"]
    }
  },
  "include": ["lens_id", "patent_citations", "scholarly_citations", "references"]
}'

data <- lens2r::get_scholarly_df(query = request)

data_json <- lens2r::get_scholarly_df(query = request, output = "json")

Get title and patent citations for a scholarly work using a doi

{ "query": { "match":{ "doi": "10.1109/ee.1934.6540358" } }, "include":["title","patent_citations"] }

Get scholarly works using multiple pmid

{ "query": { "terms": { "pmid": ["14297189", "17475107"] } } }

Get the metadata for scholarly works that are cited by a list of patents using the patent lens_id

{ "query": { "terms": { "patent_citation.lens_id":["198-832-374-467-397", "092-513-162-449-806"] } } }

Find the 10 most recently published works from an institution (sorted by published date)

{ "query": {"match_phrase": {"author.affiliation.name": "Harvard University"}}, "sort": [{"date_published": "desc"}], "size": 10 }

Get publication year of journal articles cited by patents

{ "query": { "bool" : { "must": [ {"terms": { "patent_citation.lens_id": ["020-159-299-402-960", "014-680-767-794-441"]}}, {"match": {"source.type": "Journal"}} ] } }, "include": ["year_published"], "size": 50 }

Get 30 works from an institution published between two years

{ "query": { "bool": { "must": {"match_phrase": {"author.affiliation.name": "Harvard University"}}, "filter": { "range": { "year_published": { "gte": "1999", "lte": "2000" } } } } }, "size": 30 }

Get scholarly works having patent citations and affiliations

{ "query": { "bool":{ "must": [ {"match": {"has_patent_citations": true}}, {"match": {"has_affiliation": true}} ] } } }

Query by author name

{ "query": { "match_phrase": {"author.display_name": "Craig Venter"} }, "sort": [{"year_published": "desc"}], "size": 10 }

Find scholarly works with a Pubmed identifier published in 2012

{ "query": { "bool":{ "must":[ {"match":{"external_id_type": "pmid"}}, {"match":{"year_published": 2012}} ] } }, "include":["patent_citations_count", "external_ids"] }

OR using String Based Query

{ "query": "external_id_type: pmid AND year_published: 2012", "include":["patent_citations_count", "external_ids"] }

Access your collection

[POST] https://api.lens.org/collections/123456

{
  "query": {"match": {"title": "Malaria"}},
  "include":["title","lens_id", "authors.first_name"],
  "size":10
}

Using GET Requests

[GET] https://api.lens.org/collections/123456?token=[your-access-token]&size=10&query=Malaria&include=authors,lens_id&sort=desc(date_published)

[GET] https://api.lens.org/scholarly/search?token=[your-access-token]&size=10&query=Malaria&include=authors,lens_id&sort=desc(date_published)

---

API Endpoints

Scholarly Works:

[POST] https://api.lens.org/scholarly/search
[GET] https://api.lens.org/scholarly/search
Collections:

[POST] https://api.lens.org/collections/{collection_id}
[GET] https://api.lens.org/collections/{collection_id}

Response

Response Fields Sample API Response

Response Fields Field Type Description Example patent_citations Array of Patent Citation Referenced by patents
patent_citations_count Integer Number of patent citations 10 lens_id String Unique lens identifier 100-004-910-081-14X created Date Record created date 2016-08-01T00:00:00+00:00 publication_type String Publication Type journal article publication_supplementary_type Array of String Supplementary publication type ["review"] authors Array of Author Authors
title String Title of the scholarly work Malaria external_ids Array of Id The external identifier(s) for a scholarly work (DOI, PubMed ID, PubMed Central ID, Microsoft Academic ID or CORE)
start_page String Start page 893 end_page String End page 916 volume String Volume 32 issue String Issue 4 languages Array of String Languages ["ENG"] references List of Reference References
scholarly_citations List of Lens Ids Scholarly Citations ["091-720-300-990-437"] chemicals List of Chemical Chemicals
clinical_trials List of Clinical Trial Clinical Trials
fields_of_study List of String Fields Of Study ["Immunology", "Malaria"] source_urls List of Source URL Source Urls
abstract String Scholarly work abstract text
date_published Date Date of publication 2009-05-22 year_published Integer Year of publication 1986 conference Conference The conference instance or edition
author_count Integer Number of Authors 4 references_count Integer The number of works in the reference list of a scholarly work 2 scholarly_citations_count Integer The number of scholarly works that cite this scholarly work 3 open_access Open Access
source Source Source publication in which the scholarly work appears
keywords Array of String Keywords
mesh_terms Array of MeSH Term MeSH term
funding Array of Funding Funding
Patent Citation Field Type Description Example lens_id String Unique lens identifier 141-171-521-309-804 Author Field Type Description Example collective_name String Author Collective Name
first_name String The author’s first name Alexander last_name String The author’s last name Kupco initials String Author Initials A affiliations Array of Affiliation The institution/affiliations associated with Author.
ids Array of Id Author’s MAG, ORCID identifiers [{"type": "magid", "value": "1234567890"}] Affiliation Field Type Description Example name String The institution associated with the author affiliations. Stony Brook University grid_id String Affiliation grid id grid.9018.0 country_code String Comma separated country codes DE Reference Field Type Description Example lens_id String Unique lens identifier 071-957-228-698-625 Open Access Field Type Description Example license String The Open Access license type cc-by colour String The Open Access colour category gold Source Field Type Description Example title String The name of source publication in which the scholarly work appears Journal name, Book title, Confernce proceedings type String Source Type Journal publisher String The publisher of the source publication W.B. Saunders Ltd issn Array of Object The International Standard Serial Number of the source publication, without hyphenation [{"value": "10797114"}] country String The publisher’s country United Kingdom asjc_codes String The All Science Journal Classification (ASJC) code 2735 asjc_subjects String Subject is derived from journals descriptions in Crossref metadata based on the Science Journal Classification Codes Pediatrics Mesh Term Field Type Description Example mesh_id String MeSH term unique identifier. MeSH terms are the National Library of Medicine’s controlled vocabulary or subject heading list. D000293 mesh_heading String MeSH terms are the National Library of Medicine’s controlled vocabulary or medical subject headings assigned to PubMed entries. NB MeSH Headings are case sensitive. Adolescent qualifier_id String Mesh Term Qualifier ID Q000032 qualifier_name String Mesh Term Qualifier Name analysis Funding Field Type Description Example org String Name of the funding organisation NIDCR NIH HHS funding_id String The funding organisation’s project identifier U01 DE018902 country String The country of the funding body United States Conference Field Type Description Example name String Conference Name International Electron Devices Meeting instance String Conference Instance Name CHI 1985 location String The location of the conference Lihue, Kauai, HA, USA Chemical Field Type Description Example mesh_id String MeSH term id D000293 registry_number String Chemical registration number 5Q7ZVV76EI substance_name String Substance name Antimalarials Clinical Trial Field Type Description Example id String Identifier nct00105716 registry String Clinical Trial Registry 10.18810/clinical-trials-gov Source URL Field Type Description Example type String Source URL Type html url String URL String http://cds.cern.ch/record/2291692 ID Field Type Description Example type String The type/s of external identifiers for the scholarly work doi, pmid, magid value String The external identifier(s) for a scholarly work 10.1016/s0031-3955(16)34861-1 Sample API Response

Request:

{ "query":{ "match":{"lens_id":"086-713-276-176-892"} } }

Response:

{ "total": 1, "data": [ { "patent_citations": [ { "lens_id": "122-064-734-901-067" } ], "patent_citations_count": 1, "lens_id": "086-713-276-176-892", "created": "2018-05-12T02:39:28.395000+00:00", "open_access": { "license": "cc-by-nc-nd", "colour": "hybrid" }, "publication_type": "journal article", "publication_supplementary_type": [ "clinical trial, phase ii", "multicenter study", "randomized controlled trial", "research support, non-u.s. gov't" ], "authors": [ { "collective_name": null, "first_name": "Maha", "last_name": "Hussain", "initials": "M", "affiliations": [ { "name": "University of Michigan", "grid_id": "grid.214458.e", "country_code": "US" } ] }, { "collective_name": null, "first_name": "Dana E.", "last_name": "Rathkopf", "initials": "DE", "affiliations": [ { "name": "Memorial Sloan Kettering Cancer Center", "grid_id": "grid.51462.34", "country_code": "US" } ] }, { "collective_name": null, "first_name": "Glenn", "last_name": "Liu", "initials": "G", "affiliations": [ { "name": "University of Wisconsin-Madison", "grid_id": "grid.14003.36", "country_code": "US" } ] }, { "collective_name": null, "first_name": "Andrew J.", "last_name": "Armstrong", "initials": "AJ", "affiliations": [ { "name": "Duke University", "grid_id": "grid.26009.3d", "country_code": "US" } ] }, { "collective_name": null, "first_name": "Kevin", "last_name": "Kelly", "initials": "K", "affiliations": [ { "name": "Thomas Jefferson University", "grid_id": "grid.265008.9", "country_code": "US" } ] }, { "collective_name": null, "first_name": "Anna C.", "last_name": "Ferrari", "initials": "AC", "affiliations": [ { "name": "New York University", "grid_id": "grid.137628.9", "country_code": "US" } ] }, { "collective_name": null, "first_name": "John D.", "last_name": "Hainsworth", "initials": "JD", "affiliations": [ { "name": "Sarah Cannon Research Institute", "grid_id": "grid.477834.b", "country_code": "GB" } ] }, { "collective_name": null, "first_name": "Adarsh", "last_name": "Joshi", "initials": "A", "affiliations": [ { "name": "Eli Lilly and Company", "grid_id": "grid.488258.b", "country_code": "IT" } ] }, { "collective_name": null, "first_name": "Rebecca R.", "last_name": "Hozak", "initials": "RR", "affiliations": [ { "name": "Eli Lilly and Company", "grid_id": "grid.488258.b", "country_code": "IT" } ] }, { "collective_name": null, "first_name": "Ling", "last_name": "Yang", "initials": "L", "affiliations": [ { "name": "Eli Lilly and Company", "grid_id": "grid.488258.b", "country_code": "IT" } ] }, { "collective_name": null, "first_name": "Jonathan D.", "last_name": "Schwartz", "initials": "JD", "affiliations": [ { "name": "Eli Lilly and Company", "grid_id": "grid.488258.b", "country_code": "IT" } ] }, { "collective_name": null, "first_name": "Celestia S.", "last_name": "Higano", "initials": "CS", "affiliations": [ { "name": "University of Washington", "grid_id": "grid.34477.33", "country_code": "US" } ] } ], "title": "A randomised non-comparative phase II trial of cixutumumab (IMC-A12) or ramucirumab (IMC-1121B) plus mitoxantrone and prednisone in men with metastatic docetaxel-pretreated castration-resistant prostate cancer", "volume": "51", "issue": "13", "languages": [ "en" ], "references": [ { "lens_id": "003-415-704-045-340" }, { "lens_id": "006-027-163-131-418" }, { "lens_id": "007-652-362-542-447" }, { "lens_id": "010-839-632-959-305" }, { "lens_id": "013-690-046-069-453" }, { "lens_id": "015-449-984-502-884" }, { "lens_id": "015-767-931-570-158" }, { "lens_id": "018-245-327-947-052" }, { "lens_id": "020-963-415-260-304" }, { "lens_id": "026-332-934-265-841" }, { "lens_id": "028-101-820-366-93X" }, { "lens_id": "032-523-762-689-478" }, { "lens_id": "037-117-740-052-570" }, { "lens_id": "038-557-040-762-884" }, { "lens_id": "040-239-601-782-040" }, { "lens_id": "042-246-996-698-043" }, { "lens_id": "043-024-349-674-734" }, { "lens_id": "043-201-312-439-671" }, { "lens_id": "046-041-414-632-674" }, { "lens_id": "046-648-350-541-685" }, { "lens_id": "046-852-526-558-260" }, { "lens_id": "054-808-246-993-497" }, { "lens_id": "059-727-763-246-876" }, { "lens_id": "065-982-455-260-233" }, { "lens_id": "069-612-901-254-771" }, { "lens_id": "070-794-057-102-152" }, { "lens_id": "083-233-359-584-62X" }, { "lens_id": "087-375-055-670-659" }, { "lens_id": "087-458-139-690-01X" }, { "lens_id": "090-234-280-758-859" }, { "lens_id": "094-489-992-059-749" }, { "lens_id": "095-400-716-937-253" }, { "lens_id": "096-654-301-744-608" }, { "lens_id": "101-625-667-760-940" }, { "lens_id": "113-073-836-369-700" }, { "lens_id": "128-335-721-572-401" }, { "lens_id": "155-152-241-876-905" } ], "keywords": [ "Cixutumumab", "Mitoxantrone", "Prednisone", "Prostate cancer", "Ramucirumab" ], "mesh_terms": [ { "mesh_heading": "Adenocarcinoma", "qualifier_name": "drug therapy", "mesh_id": "D000230", "qualifier_id": "Q000188" }, { "mesh_heading": "Adolescent", "mesh_id": "D000293" }, { "mesh_heading": "Adult", "mesh_id": "D000328" }, { "mesh_heading": "Aged", "mesh_id": "D000368" }, { "mesh_heading": "Antibodies, Monoclonal", "qualifier_name": "administration & dosage", "mesh_id": "D000911", "qualifier_id": "Q000008" }, { "mesh_heading": "Antineoplastic Combined Chemotherapy Protocols", "qualifier_name": "adverse effects", "mesh_id": "D000971", "qualifier_id": "Q000009" }, { "mesh_heading": "Disease Progression", "mesh_id": "D018450" }, { "mesh_heading": "Disease-Free Survival", "mesh_id": "D018572" }, { "mesh_heading": "Docetaxel", "mesh_id": "D000077143" }, { "mesh_heading": "Humans", "mesh_id": "D006801" }, { "mesh_heading": "Kaplan-Meier Estimate", "mesh_id": "D053208" }, { "mesh_heading": "Male", "mesh_id": "D008297" }, { "mesh_heading": "Middle Aged", "mesh_id": "D008875" }, { "mesh_heading": "Mitoxantrone", "qualifier_name": "administration & dosage", "mesh_id": "D008942", "qualifier_id": "Q000008" }, { "mesh_heading": "Prednisone", "qualifier_name": "administration & dosage", "mesh_id": "D011241", "qualifier_id": "Q000008" }, { "mesh_heading": "Proportional Hazards Models", "mesh_id": "D016016" }, { "mesh_heading": "Prostatic Neoplasms, Castration-Resistant", "qualifier_name": "drug therapy", "mesh_id": "D064129", "qualifier_id": "Q000188" }, { "mesh_heading": "Taxoids", "qualifier_name": "therapeutic use", "mesh_id": "D043823", "qualifier_id": "Q000627" }, { "mesh_heading": "Time Factors", "mesh_id": "D013997" }, { "mesh_heading": "Treatment Outcome", "mesh_id": "D016896" }, { "mesh_heading": "United States", "mesh_id": "D014481" }, { "mesh_heading": "Young Adult", "mesh_id": "D055815" } ], "chemicals": [ { "substance_name": "Antibodies, Monoclonal", "registry_number": "0", "mesh_id": "D000911" }, { "substance_name": "Taxoids", "registry_number": "0", "mesh_id": "D043823" }, { "substance_name": "anti-IGF-1R antibody A12", "registry_number": "0", "mesh_id": "C557414" }, { "substance_name": "Docetaxel", "registry_number": "15H5577CQD", "mesh_id": "D000077143" }, { "substance_name": "Mitoxantrone", "registry_number": "BZ114NVM5P", "mesh_id": "D008942" }, { "substance_name": "ramucirumab", "registry_number": "D99YVK4L0X", "mesh_id": "C543333" }, { "substance_name": "Prednisone", "registry_number": "VB0R961HZT", "mesh_id": "D011241" } ], "clinical_trials": [ { "id": "nct00683475", "registry": "10.18810/clinical-trials-gov" } ], "fields_of_study": [ "M.2", "Immunology", "Cixutumumab", "Prednisone", "Ramucirumab", "Prostate cancer", "Mitoxantrone", "Docetaxel", "Regimen", "Medicine" ], "funding": [ { "org": "NCI NIH HHS", "funding_id": "P30 CA008748", "country": "United States" } ], "source_urls": [ { "type": "unknown", "url": "http://www.ejcancer.com/article/S0959-8049(15)00450-5/pdf" }, { "type": "html", "url": "https://www.ncbi.nlm.nih.gov/pmc/articles/PMC5024789/" }, { "type": "html", "url": "https://www.scholars.northwestern.edu/en/publications/a-randomised-non-comparative-phase-ii-trial-of-cixutumumab-imc-a1" }, { "type": "html", "url": "https://www.sciencedirect.com/science/article/pii/S0959804915004505" }, { "type": "core_fulltext", "url": "https://core.ac.uk/download/pdf/82196673.pdf" } ], "abstract": "Abstract Background Cixutumumab, a human monoclonal antibody (HuMAb), targets the insulin-like growth factor receptor. Ramucirumab is a recombinant HuMAb that binds to vascular endothelial growth factor receptor-2. A non-comparative randomised phase II study evaluated cixutumumab or ramucirumab plus mitoxantrone and prednisone (MP) in metastatic castration-resistant prostate cancer (mCRPC). Patients and methods Men with progressive mCRPC during or after docetaxel therapy received mitoxantrone 12 mg/m 2 on day 1 and prednisone 5 mg twice daily and were randomised 1:1 to receive either cixutumumab or ramucirumab 6 mg/kg intravenously weekly in a 21-day cycle. Primary end-point was composite progression-free survival (cPFS). Secondary end-points included safety, response, radiographic progression-free survival (PFS) and overall survival (OS). Sample size was based on a 50% increase in median cPFS from 2.6 (MP) to 3.9 months (either combination). Results 132 men were treated (66 per arm). Median cPFS was 4.1 months (95% confidence interval (CI), 2.2–5.6) for cixutumumab and 6.7 months (95% CI, 4.5–8.3) for ramucirumab. Median time to radiographic progression was 7.5 months for cixutumumab and 10.2 months for ramucirumab, with a median OS of 10.8 and 13.0 months, respectively. Fatigue was the most frequent adverse event (AE). Incidence of most non-haematologic grade 3–4 AEs was Conclusion Combinations of cixutumumab or ramucirumab plus MP were feasible and associated with moderate toxicities in docetaxel-pretreated men with mCRPC. Of the two regimens, the ramucirumab regimen is worthy of further testing based on the observed cPFS relative to the historical control.", "year_published": 2015, "references_count": 37, "scholarly_citations_count": 10, "external_ids": [ { "type": "magid", "value": "2113210954" }, { "type": "pmid", "value": "26082390" }, { "type": "doi", "value": "10.1016/j.ejca.2015.05.019" } ], "start_page": "1714", "end_page": "1724", "source": { "title": "European Journal of Cancer", "type": "Journal", "publisher": "Elsevier BV", "issn": [ { "value": "09598049" } ], "country": "United Kingdom", "asjc_codes": [ "1306", "2730" ], "asjc_subjects": [ "Oncology", "Cancer Research" ] }, "scholarly_citations": [ "000-201-187-558-654", "026-107-871-228-662", "028-262-672-178-175", "030-115-779-382-725", "035-630-845-016-108", "037-016-998-061-439", "062-343-220-167-149", "067-043-485-486-441", "145-126-752-104-913", "174-636-795-252-301" ], "author_count": 12, "date_published": "2015-06-13T00:00:00+00:00" } ], "results": 1 }

Copyright © 2020

---

Request

The request fields are used in queries and sort operations.

Request Structure Searchable Fields Filters Pagination Sorting Projection Supported Query Types

Request Structure

The request payload should comply with following json schema. Fields Description Required query Valid json search request true sort Use available fields to sort results by ascending/descending order. false include Only get specific fields from API response. By default all fields are selected. false exclude Get all fields except undesired ones in search result. false size Integer value to specify number of items per page false from Integer value, defines the offset from the first result false scroll_id Pagination parameter false (true for next scroll requests) scroll Lifespan of Scroll scroll context in minute (e.g. 1m) false (true for scroll context) Searchable Fields

For searching, following fields are supported by the system: Field Type Description lens_id String Unique lens identifier e.g. 100-004-910-081-14X patent_citation.lens_id String ID of Referenced by patents patent_citation_count Integer Number of patent citations external_id_type String External Identifier type (Crossref: doi, Microsoft Academic: magid, PubMed: pmid, PubMed Central: pmcid, CORE: coreid) doi String Crossref DOI Identifier pmid String PubMed ID Identifier pmcid String PubMed Central ID Identifier magid String Microsoft Academic ID coreid String CORE Identifier created Date Record created date e.g. 2018-05-12, 2016-08-01T00:00:00+00:00 publication_type String Publication Type conference proceedings, book chapter, journal article, component, conference proceedings article, dataset, libguide, reference entry, book publication_supplementary_type String Supplementary publication type e.g. review, comparative study, research support author.collective_name String Author Collective Name author.first_name String The author’s first name e.g. Alexander author.last_name String The author’s last name e.g. Kupco author.initials String Author Initials e.g. A author.display_name String Author’s full name e.g. Alexander Kupco author.magid String Author MAG identifier author.orcid String Author ORCID identifier author.affiliation.name String The institution associated with the author affiliations. e.g. Stony Brook author.affiliation.name.exact String Exactly matches the full institution name (case sensetive). e.g. Stony Brook University author.affiliation.grid_id String Affiliation grid id e.g. grid.9018.0 author.affiliation.country_code String Country Code e.g. US,DE,CH, FR title String Title of the scholarly work e.g. Malaria language String Languages e.g. en, de, fr, zh_chs chemical.mesh_id String MeSH term id e.g. D000293 chemical.registry_number String Chemical registration number e.g. 5Q7ZVV76EI chemical.substance_name String Substance name e.g. Antimalarials clinical_trial.id String Clinical trial Identifier e.g. nct00105716 clinical_trial.registry String Clinical Trial Registry e.g. 10.18810/clinical-trials-gov field_of_study String Fields Of Study e.g. Immunology, Malaria abstract String Scholarly work abstract text full_text String Full Text date_published Date Date of publication e.g. 2009-05-22 year_published Integer Year of publication e.g. 1986 conference.name String Conference Name e.g. International Electron Devices Meeting conference.instance String Conference Instance Name e.g. CHI 1985 conference.location String The location of the conference e.g. Lihue, Kauai, HA, USA author_count Integer Number of Authors reference_count Integer The number of works in the reference list of a scholarly work scholarly_citation_count Integer The number of scholarly works that cite this scholarly work open_access.license String The Open Access license type e.g. cc-by open_access.colour String The Open Access colour category e.g. gold, green source.title String The name of source publication in which the scholarly work appears e.g. Journal name, Book title, Conference proceedings source.title.exact String The full name of source publication for exact match (case sensetive). source.type String Source Type e.g. Journal, Book Series source.publisher String The publisher of the source publication Elsevier, Wiley, American Medical Association source.issn String The International Standard Serial Number of the source publication, without hyphenation e.g. 00222836 source.country String The publisher’s country e.g. United States, United Kingdom source.asjc_codes String The All Science Journal Classification (ASJC) code e.g. 2735 source.asjc_subjects String Subject is derived from journals descriptions in Crossref metadata based on the Science Journal Classification Codes e.g. Pediatrics, Microbiology, Biophysics keyword String Search Keywords mesh_term.mesh_id String MeSH term unique identifier. MeSH terms are the National Library of Medicine’s controlled vocabulary or subject heading list. e.g. D000293 mesh_term.mesh_heading String MeSH terms are the National Library of Medicine’s controlled vocabulary or medical subject headings assigned to PubMed entries. e.g. Phosphates, Immunochemistry mesh_term.qualifier_id String Mesh Term Qualifier ID e.g. Q000032 mesh_term.qualifier_name String Mesh Term Qualifier Name e.g. pathology, immunology, analysis funding.organisation String Name of the funding organisation e.g. NIDCR NIH HHS funding.organisation.exact String For exact matches of full organisational name (case sensetive). funding.funding_id String The funding organisation’s project identifier e.g.U01 DE018902 funding.country String The country of the funding body e.g. United States, Germany, United Kingdom Filtering

You can use following pre-defined filters to refine search results: Field Description Possible Value has_patent_citations Indicates if the scholarly work has been cited by a patent document. true/false has_affiliation Has affiliation true/false has_affiliation_grid Has affiliation grid true/false has_mesh_term Has MeSH term true/false has_chemical Indicates if the scholarly work has an associated chemical substance true/false has_keyword Indicates if the scholarly work has keyword true/false has_clinical_trial Indicates if the scholarly work has clinical trial true/false has_field_of_study Flags if the scholarly work has a Field of Study true/false has_abstract Indicates if the scholarly work has abstract true/false has_fulltext Indicates if the scholarly work has fulltext true/false has_funding Indicates if the scholarly work has funding information true/false is_open_access Flags if the scholarly work has is Open Access true/false

Example:

{ "query": { "match":{ "has_patent_citations": true } } }

Pagination

Lens API provides two type of pagination based on their use: Offset/Size Based Pagination

Use parameter from to define the offset and size to specify number of records expected. This is useful when you want to skip some records and select desired ones. Example below skips first 100 and select 50 records after that.

{ "query": "Malaria", "from": 100, "size":50 }

Similarly for GET requests, the following parameters are applicable: size=50&from=100

Note:

    Offset/size based paginations is suitable for small result sets only and does not work on result sets of more that 1000 records. For larger volume data downloads, use Cursor Based Pagination.

Cursor Based Pagination

You can specify records per page using size (default 20 and max 1000) and context alive time scroll (default 1 minute). You will receive a scroll_id in response, which should be passed via request body to access next set of results. Since the scroll_id tends to change every time after each successful requests, please use the most recent scroll_id to access next page. This is not suited for real time user requests.

{ "scroll_id": "MjAxOTEw;DnF1ZXJ...R2NZdw==", "scroll": "1m" }

Note:

    The lifespan of scroll_id is limited to 1 minute for the current API version. Using expired scroll_id will result bad request HTTP response.
    Parameter size will be used for first scroll query and will remain the same for whole scroll context. Hence, using size in each scroll request will not have any effect.
    Cursor based pagination is only applicable to POST requests.

Sorting

Result can be retrieved in ascending or descending order. By default, results are sorted with most relevant matches first. Use the following format and fields to apply sorting to the API response.

{ "sort": [ {"patent_citation_count":"asc"}, {"year_published": "desc"} ] }

For GET requests following structure is applicable. sort=desc(date_published),asc(patent_citation_count) Projection

You can control the output fields in the API Response using projection. There are two possible ways to do that.

include: Only request specific fields from the API endpoint
exclude: Fields to be excluded from result

{"include":["title","patent_citations","authors.affiliations.name"]}

{"exclude":["external_ids","references"]}

For GET requests following structure is applicable. include=authors,lens_id

Note: Both include and exclude can be used in same request.

Supported Query Types

Following queries are supported by current version of Lens API: Term Query

Term Query operates in a single term and search for exact term in the field provided.

Example: Find record by publication type

{
    "query": {
        "term": {
            "publication_type": "journal article"
        }
    }
}

Terms Query

Terms Query allows you to search multiple exact terms for a provided field. A useful scenario is while searching multiple identifiers.

Example: Search scholarly works for multiple pmid

{
    "query": {
        "terms": {
            "pmid": ["14297189", "17475107"]
        }
    }
}

Match query

Match query accepts text/numbers/dates. The main use case of the match query is full-text search. It matches each words separately. If you need to search whole phrase use match phrase query.

Example:

{
  "query": {
        "match":{
            "author.affiliation.name": "Harvard University"
        }
   }
}

Match Phrase query

Match phrase query accepts text/numbers/dates. The main use case for the match query is for full-text search.

Example:

{
  "query": {
        "match_phrase":{
            "author.affiliation.name": "Harvard University"
        }
   }
}

Range query

Range query query to match records within the provided range.

Example: Get record for year published between years 1980 and 2000

{
  "query": {
        "range": {
            "year_published": {
                "gte": "1980",
                "lte": "2000"
            }
        }
   }
}

Boolean query

Bool Query allows to combine multiple queries to create complex query providing precise result. It can be created using one or more of these clauses: must, should, must_not and filter. You can use must for AND operation and should for OR.

Example: Get journal article scholarly works of Author with last name Kondratyev having patent citations.

{
 "query": {
   "bool": {
     "must": [{
       "match": {
         "has_patent_citations": true
       }},
       {"bool": {
         "must": [
           {"match": {"publication_type": "journal article"}},
           {"match": {"author.last_name": "Kondratyev"}}
         ]
       }
       }
     ]
   }
 }
}

Query String Based Query

Query different terms with explicit operators AND/OR/NOT to create a compact query string.

Example: Find works from institution published between two dates having some title.

{"query": "(title:Dimensions AND author.affiliation.name:(Harvard University)) AND year_published:[2000 TO 2018]"}

If you need to use any reserved special characters, you should escape them with leading backslash.

Example: Getting by doi identifier using string based query

{"query": "doi:10.1109\\/ee.1934.6540358"}

You can use json based format for string based query and mixed with complex boolean queries like this:

{ "query": { "bool": { "must": [{ "query_string": { "query": "X-ray analysis of protein crystals", "fields": ["title", "abstract", "full_text"], "default_operator": "and" } }], "filter": [{ "term": { "has_affiliation": true } }]

    }
}

}

Copyright © 2020

---

---

Home Getting Started Request Response Examples Code Samples Support Getting Started

Prerequisites API Endpoints API Access Rate Limiting HTTP Responses

Prerequisites

You need to have the following before you can start using Lens APIs:

Granted access to our API service.
Create an Access Token from your user profile page.
Basic knowledge of API structure and JSON formatting.
Any API Client (cURL, Postman, etc.)

API Endpoints

As of the current version, Lens offers the following API endpoints:

Scholarly Works:

[POST] https://api.lens.org/scholarly/search
[GET] https://api.lens.org/scholarly/search

Collections:

[POST] https://api.lens.org/collections/{collection_id}
[GET] https://api.lens.org/collections/{collection_id}

You can access scholarly works in your collections from your Work Area. The {collection_id} can be found at the end of your collection URL, e.g. https://www.lens.org/lens/scholar/search/results?collectionId={collection_id}. Here is an example to illustrate how to access your collection.

API usage:

[GET] https://api.lens.org/scholarly/usage

Swagger Documentation is available here: https://api.lens.org/swagger-ui.html API Access

Your use of the API is subject to the Lens Terms of Use. Lens uses token-based API authentication, you can request access and manage your access plan and tokens from your Lens user profile.

For POST Requests, you need to provide your access token in the Request Header when accessing the APIs:

Example: Authorization: Bearer your-access-token

For GET Requests, you can provide your access token in the request parameter:

Example: https://api.lens.org/scholarly/search?token=your-access-token

Rate Limiting

To ensure our public API endpoints remain usable by everyone and to maintain the server’s optimal availability, a rate limiting mechanism is being used to temporarily block any clients that reduce the server’s performance. The applied rate limits will be included in the following HTTP response headers:

x-rate-limit-remaining-request-per-minute: Number of requests allowed in a minute
x-rate-limit-retry-after-seconds: Time in seconds until next request can be performed
x-rate-limit-reset-date: Rate limit will get reset at this date
x-rate-limit-remaining-request-per-month: Number of API calls allowed till the reset date above
x-rate-limit-remaining-record-per-month: Number of remaining records that can be fetched

Once you go over any rate limit you will receive a 429 - Too many requests error with respective messages. HTTP Responses Response Description 200 - Ok Valid response from the server 400 - Bad Request Malformed request or incorrect fields/values provided 401 - Unauthorized Authentication credentials might be incorrect or missing 404 - Not Found Incorrect Resource URL / Empty Result for supplied queries / Expired scroll_id 415 - Unsupported Media Type Request body is not json or Content Type is not application/json 429 - Too Many Requests You have exceeded the number of allowed calls 50x - Internal Server Error An error occurred on API server side.

sbalci/lens2r documentation built on Jan. 18, 2021, 9:12 a.m.