connectedpapers-js

The JS client for the connected papers API.

Installation

For npm:

npm install connectedpapers-js

For yarn:

yarn add connectedpapers-js

Usage

import { ConnectedPapersClient } from 'connectedpapers-js';

const DEEPFRUITS_PAPER_ID = "9397e7acd062245d37350f5c05faf56e9cfae0d6"

const client = new ConnectedPapersClient({access_token: "TEST_TOKEN"});
client.getGraph({paper_id: DEEPFRUITS_PAPER_ID, fresh_only: true}).then((paper) => {
  console.log(paper);
});
client.getRemainingUsages().then((remainingUses) => {
  console.log(`Remaining uses: ${remainingUses}`);
});
client.getFreeAccessPapers().then((freeAccessPapers) => {
  console.log(`Free access papers: ${freeAccessPapers}`);
});

API

The following async functions are part of the connected papers API:

• getGraph({paper_id: string, fresh_only?: boolean, retry_on_overloaded?: boolean}): Returns the paper with the given ID. If fresh_only is true, then if the graph is over 30 days old, the call will wait for a rebuild. If retry_on_overloaded is true (default), automatically retries when receiving OVERLOADED status.
• getRemainingUsages(): Returns the number of remaining usages for the current API key.
• getFreeAccessPapers(): Returns the number of free access papers for the current API key.

Free access papers

If you've already accessed a paper's graph within the past 30 days, any additional access to the same graph during this period won't be counted against your usage limit. Such repeated access is considered "free," and the paper in question is referred to as a "free access paper."

Rate Limiting and OVERLOADED Status

The Connected Papers API implements per-API-key rate limiting (default: 5 builds per minute). When rate limits are exceeded or the system is overloaded, the API returns an OVERLOADED status.

Automatic Retry on OVERLOADED

By default, the client automatically retries requests when receiving an OVERLOADED status with exponential backoff delays:

• 1st retry: 5 seconds
• 2nd retry: 10 seconds
• 3rd retry: 20 seconds
• 4th retry: 40 seconds

After 4 retry attempts, the OVERLOADED status is returned to the caller.

Disabling Automatic Retry

You can disable automatic retry by setting retry_on_overloaded: false:

const response = await client.getGraph({
  paper_id: PAPER_ID,
  fresh_only: true,
  retry_on_overloaded: false
});

if (response.status === GraphResponseStatuses.OVERLOADED) {
  console.log("System is overloaded, please try again later");
}

Higher Rate Limits

If you need higher rate limits for your use case, please contact us at [email protected].

Supplying an API key

There are two ways to supply an API key to the client:

• Set the CONNECTED_PAPERS_API_KEY environment variable.

export CONNECTED_PAPERS_API_KEY="<your api key>"

Then create the client without any arguments:

const client = new ConnectedPapersClient();

• Pass the API key as an argument to the constructor:

const client = new ConnectedPapersClient({access_token: "<your api key>"});

Getting an API key

To get an early-access API key, contact us at [email protected].

You can use the API key TEST_TOKEN to access the graph of the paper with ID 9397e7acd062245d37350f5c05faf56e9cfae0d6 for testing purposes.

Paper IDs

We use ShaIDs by Semantic Scholar as paper IDs. You can find the ShaID of a paper by going to its Semantic Scholar page and copying the ID from the URL. For example, the ShaID of the paper DeepFruits: A Fruit Detection System Using Deep Neural Networks is 9397e7acd062245d37350f5c05faf56e9cfae0d6.

Async iterator access

The client also supports async iterator access to the API. This is useful for tracking the progress of graph builds and getting existing as well as rebuilt papers.

Calling the getGraphAsyncIterator returns an async iterator that yields the GraphResponse type:

export enum GraphResponseStatuses {
  BAD_ID = 'BAD_ID',
  ERROR = 'ERROR',
  NOT_IN_DB = 'NOT_IN_DB',
  OLD_GRAPH = 'OLD_GRAPH',
  FRESH_GRAPH = 'FRESH_GRAPH',
  IN_PROGRESS = 'IN_PROGRESS',
  QUEUED = 'QUEUED',
  BAD_TOKEN = 'BAD_TOKEN',
  BAD_REQUEST = 'BAD_REQUEST',
  OUT_OF_REQUESTS = 'OUT_OF_REQUESTS',
  OVERLOADED = 'OVERLOADED',
}

export type GraphResponse = {
  status: GraphResponseStatuses;
  graph_json?: Graph;
  progress?: number;
};

Once the status is one of BAD_ID, ERROR, NOT_IN_DB, BAD_TOKEN, BAD_REQUEST, OUT_OF_REQUESTS, or OVERLOADED (after retries if enabled), the iterator will stop yielding values.

Signature:

class ConnectedPapersClient {
  // ...
  public async* getGraphAsyncIterator(args: {
    paper_id: PaperId;
    fresh_only?: boolean;
    loop_until_fresh?: boolean;
    retry_on_overloaded?: boolean;
  }): AsyncGenerator<GraphResponse>;
}

Call with fresh_only = false, loop_until_fresh = true to get the currently existing graph and keep waiting for a rebuild.

The response will have status GraphResponseStatuses.OLD_GRAPH in the first response, then it will go throught the GraphResponseStatuses.QUEUED, GraphResponseStatuses.IN_PROGRESS states with the progress field set to the percentage of the graph build that is done. When the rebuild is done, the status will be GraphResponseStatuses.FRESH_GRAPH and the loop will stop. The graph_json field will have the graph at each of these responses.