Package: connectedpapers-py
connectedpapers-pyThe official python client for the connected papers API.Installationpipinstallconnectedpapers-pyUsagefromconnectedpapersimportConnectedPapersClientDEEPFRUITS_PAPER_ID="9397e7acd062245d37350f5c05faf56e9cfae0d6"# TEST_TOKEN allows access ONLY to the paper with the id DEEPFRUITS_PAPER_IDclient=ConnectedPapersClient(access_token="TEST_TOKEN")remaining_uses_count=client.get_remaining_usages_sync()print(f"Remaining uses count:{remaining_uses_count}")free_access_papers=client.get_free_access_papers_sync()print(f"Free access papers:{free_access_papers}")graph=client.get_graph_sync(DEEPFRUITS_PAPER_ID)assertgraph.graph_json.start_id==DEEPFRUITS_PAPER_IDSee more on theusage samplesdirectory.See graph structure atgraph.py.Configuring the API keyThere are multiple ways to configure the server address and API key:Set the environment variableCONNECTED_PAPERS_API_KEY:exportCONNECTED_PAPERS_API_KEY="YOUR_API_KEY"Then you can use the client without parameters:fromconnectedpapersimportConnectedPapersClientclient=ConnectedPapersClient()Send parameters to the client's constructur:fromconnectedpapersimportConnectedPapersClientclient=ConnectedPapersClient(access_token="YOUR_API_KEY")Getting an access tokenContact us athello@connectedpapers.comto get
an early-access access token.Using the tokenTEST_TOKENor not passing a token at all,
will allow you to access the graph of the paper with the id9397e7acd062245d37350f5c05faf56e9cfae0d6for testing purposes.Paper IDsWe use the ShaIDs fromSemantic Scholaras paper IDs.
You can find the ShaID of a paper by searching for it on Semantic Scholar and copying the ID from the URL.APIMost functions offer a synchronous and an asynchronous version.If a graph is already built, you can get it within a standard API call latency.
If it is outdated (older than 1 month), you can still get it using thefresh_only=Falseparameter.
If you wait for a rebuild (eitherfresh_only=Trueand graph older than 30 days, or no graph built for the paper)
a rebuild will be triggered; A graph build can take up to 1 minute, and usually around 10 seconds.The graph structure is documented atgraph.py.API structureWe have the following API calls available:Fetching a graphGetting the remaining usages count for your API keyGetting the list of papers that are free to accessFree re-access to papersIf you have fetched a paper, it remains free to access
for a month after the first access without counting
towards your usages count.Synchronous APIfromconnectedpapersimportConnectedPapersClientclient=ConnectedPapersClient(access_token="YOUR_API_KEY")client.get_graph_sync("YOUR_PAPER_ID")# Fetch a graph for a single paperclient.get_remaining_usages_sync()# Get the remaining usages count for your API keyclient.get_free_access_papers_sync()# Get the list of papers that are free to accessAsynchronous APIfromconnectedpapersimportConnectedPapersClientclient=ConnectedPapersClient(access_token="YOUR_API_KEY")asyncdefusage_sample()->None:awaitclient.get_graph_async("YOUR_PAPER_ID")# Fetch a graph for a single paperawaitclient.get_remaining_usages_async()# Get the remaining usages count for your API keyawaitclient.get_free_access_papers_async()# Get the list of papers that are free to accessusage_sample()Async iterator APIThe client offers support for Python'sasynchronous iteratoraccess to the API, allowing for real-time monitoring of
the progress of graph builds and retrieval of both current
and rebuilt papers.The methodget_graph_async_iteratorreturns an asynchronous
iterator, generating values of theGraphResponsetype. Here's what theGraphResponseand relatedGraphResponseStatuseslooks like in Python:classGraphResponseStatuses(Enum):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"@dataclasses.dataclassclassGraphResponse:status:GraphResponseStatusesgraph_json:Optional[Graph]=Noneprogress:Optional[float]=Noneremaining_requests:Optional[int]=NoneOnce the status falls into one of the terminal states (BAD_ID, ERROR, NOT_IN_DB, BAD_TOKEN, BAD_REQUEST, OUT_OF_REQUESTS), the iterator will cease to yield further values.Here's the signature for invoking this method:classConnectedPapersClient:# ...asyncdefget_graph_async_iterator(self,paper_id:str,fresh_only:bool=False,loop_until_fresh:bool=True)->AsyncIterator[GraphResponse]:# ...Call this method with fresh_only=False and loop_until_fresh=True
to request the existing graph and continue waiting
for a rebuild if necessary.The initial response will contain the status GraphResponseStatuses.OLD_GRAPH,
then transition through GraphResponseStatuses.QUEUED and
GraphResponseStatuses.IN_PROGRESS, with the progress
field reflecting the percentage of the graph build
completed. Upon completion of the rebuild,
the status will change to GraphResponseStatuses.FRESH_GRAPH,
and the iteration will end.The graph_json field will contain the graph corresponding
to each of these responses, and will remain a non-None
as long as there is any version of the graph available.