Chapter 6. STRING API

STRING has an application programming interface (API) which enables you to get the data without using the graphical user interface of the web page. The API is convenient if you need to programmatically access some information but still do not want to download the entire dataset. There are several scenarios when it is practical to use it. For example, you might need to access some interaction from your own scripts or want to incorporate some information in STRING to a web page.

We currently provide an implementation using HTTP, where the database information is accessed by HTTP requests. Due to implementation and licensing reasons, The API provide methods to query individual items only, similar to the web site. If you need access to bulk data, you can download the entire dataset by signing the academic license agreement.

API format

To call the API, make a URI (uniform resource identifier) of the following form:
		
	http://[database]/[access]/[format]/[request]?[parameter]=[value]

      
Possible values for the fields are listed below in tables 3.1-3.5. Note that only some of the combinations of the fields are possible as shown on this diagram:

API URL structure (high resolution:1073x645 pixels, file size: 57 KB, pdf:1073x645 pixels, file size: 119 KB).

As an identifier, it is possible to use either a single entry or a list of entries. The parameter is then called identifiers or identifiers, respectively. In the former case, the request should be resolve, abstracts, actions, interactors, interactions or network followed by the required parameter identifier and its value. In the latter case, when there are several entries, the request should be ending with ...List and have the required parameter identifiers. The values of the identifiers parameter contains a list of items separated by new line characters (%0A or %0D).

It is also possible to use a single item in list of identifies, for most cases this will be identical to the single item queries mentioned above.

Table 6.1. List of databases

databaseDescription
string-db.orgMain entry point of STRING
string.embl.de Alternative entry point of STRING
stitch.embl.de The sister database of STRING


Table 6.2. List of accesses

accessDescription
api Application programming interface
services Other services to access data


Table 6.3.  List of formats

format Return value
jsonJSON format either as a list of hashes/dictionaries, or as a plain list (if there is only one value to be returned per record)
tsvTab separated values, with a header line
tsv-no-headerTab separated values, without header line
psi-miThe interaction network in PSI-MI 2.5 XML format
psi-mi-tabTab-delimited form of PSI-MI (similar to tsv, modeled after the IntAct specification. (Easier to parse, but contains less information than the XML format.)
imageThe network image


Table 6.4. List of requests

requestReturn value
resolveList of items that match (in name or identifier) the query item
resolveListList of items that match (in name or identifier) the query items
abstractsList of abstracts that contain the query item
abstractsListList of abstracts that contain any of the query items
interactorsList of interaction partners for the query item
interactorsListList of interaction partners for any of the query items
actionsAction partners for the query item
actionsListAction partners for any of the query items
interactionsInteraction network in PSI-MI 2.5 format or PSI-MI-TAB format (similar to tsv)
interactionsListInteraction network as above, but for a list of identifiers
networkThe network image for the query item
networkListThe network image for the query items


Table 6.5. List of parameters and values

parametersDescriptions, value
identifierrequired parameter for single item, e.g. DRD1_HUMAN
identifiersrequired parameter for multiple items, e.g.DRD1_HUMAN%0DDRD2_HUMAN
formatFor resolve requests: only-ids get the list of only the STRING identifiers (full by default) For abstract requests: use colon pmids for alternative shapes of the pubmed identifier
speciesTaxon identifiers (e.g. Human 9606, see: http://www.uniprot.org/taxonomy)
limit Maximum number of nodes to return, e.g 10.
required_scoreThreshold of significance to include a interaction, a number between 0 and 1000
additional_network_nodes Number of additional nodes in network (ordered by score), e.g./ 10
network_flavor The style of edges in the network. evidence for colored multilines. confidence for singled lines where hue correspond to confidence score. (actions for stitch only)
caller_identity Your identifier for us.


Examples

find out which proteins match the description "ADD" in human:
 
	http://string-db.org/api/tsv/resolve?identifier=ADD&species=9606 
			
Returns bare IDs that you could pipe into other STRING API-functions:
 
	http://string-db.org/api/tsv-no-header/resolve?identifier=YOL086C&format=only-ids			
			
Maximum 10 PMID (default setting for limit) for that contain any of that identifiers.
 
	http://string-db.org/api/tsv/abstractsList 
		?identifiers=4932.YML115C%0D4932.YJR075W%0D4932.YEL036C
			
To get the 20 highest scoring interactors above score 400 for a list of queries.
 
	http://string-db.org/api/tsv-no-header/interactorsList 
		?identifiers=4932.YML115C%0D4932.YJR075W%0D4932.YEL036C 
		&required_score=400&limit=20 
			
The interactions above score 900 for a list of queries and limit to 5 nodes (i.e. max 5.6/2=15 interactions).
 
	http://string-db.org/api/psi-mi-tab/interactionsList 
		?identifiers=4932.YML115C%0D4932.YJR075W%0D4932.YEL036C 
		&required_score=900 
			
The network of a known identifier, with a score threshold of 950, limited to 10 interacting protein, and a evidence style of the edges.
 
	http://string-db.org/api/image/network?identifier=4932.YML115C 
		&required_score=950&limit=10 
		&network_flavor=evidence

Additional information about the API

As mentioned above, if you need to do large-scale analysis, please download full data set. Otherwise you may flood the string server with api requests, in particular if you run scripts in parallel.

The format of the API will stay constant with upcoming versions of STRING, but it is likely that add more query options later for retrieving information. For example: What are the synonyms of this item? To which orthologous group does this protein belong? etc.

The caller_identity parameter can be used for identifying you call to STRING. We can provide logging information according to such information. Please contact the string team if you have particular needs.