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 STRING network in your web page.
We currently provide an implementation using HTTP, where the database information is accessed by HTTP requests. Due to implementation reasons, similarly to the web site, some API methods will allow only a limited number of proteins in each query. If you need access to the bulk data, you can download the entire dataset from the download page
There are several methods available through STRING API:
| Mrethod | API method URL | Description |
|---|---|---|
| Mapping identifiers | /api/tsv/get_string_ids? | Maps common protein names, synonyms and UniProt identifiers into STRING identifiers |
| Getting the network image | /api/image/network? | Retrieves the network image with your input protein(s) highlighted in color |
| Linking to the network on STRING webpage | /api/tsv/get_link? | Get the link to STRING webpage showing your network |
| Embedding interactive network in the website | javascript:getSTRING(...) | A call that lets you embed a network with movable bubbles and protein information pop-ups in a website. |
| Retrieving the interaction network | /api/tsv/network? | Retrieves the network interactions for your input protein(s) in various text based formats |
| Getting the interaction partners | /api/tsv/interaction_partners? | Gets all the STRING interaction partners of your proteins |
| Getting protein similarity scores | /api/tsv/homology? | Retrieve the protein similarity scores between the input proteins |
| Retrieving best similarity hits between species | /api/tsv/homology_best? | Retrieve the similarity from your input protein(s) to the best (most) similar protein from each STRING species. |
| Performing functional enrichment | /api/tsv/enrichment? | Performs the enrichment analysis of your set of proteins for the Gene Ontology, KEGG pathways, UniProt Keywords, PubMed publications, Pfam, InterPro and SMART domains. |
| Retrieving functional annotation | /api/tsv/functional_annotation? | Gets the functional annotation (Gene Ontology, UniProt Keywords, PFAM, INTERPRO and SMART domains) of your list of proteins. |
| Performing interaction enrichment | /api/tsv/ppi_enrichment? | Tests if your network has more interactions than expected |
| Getting current STRING version | /api/tsv/version | Prints the current STRING version and its stable address |
Getting started Top ↑
As STRING API works like normal HTTP request you can access it like any other webpage. Just copy/paste the following URL into your browser to get the PNG image of Patched 1 gene network.
https://string-db.org/api/image/network?identifiers=PTCH1
However most likely you will be accessing the API from your scripts or website. Examples of python scripts for each of the API calls are attached at the end of each section.
In order to query with more than one identifier in one call just separate each identifier by carriage return character "\r" or "%0d" (depending how you call STRING):
https://string-db.org/api/image/network?identifiers=PTCH1%0dSHH%0dGLI1%0dSMO%0dGLI3
or from python3:
import requests ## python -m pip install requests
response = requests.get("https://string-db.org/api/image/network?identifiers=PTCH1%0dSHH%0dGLI1%0dSMO%0dGLI3")
with open('string_network.png', 'wb') as fh:
fh.write(response.content)
...but before you start coding:
- Please be considerate and wait one second between each call, so that our server won't get overloaded.
- Although STRING understands a variety of identifiers and does its best to disambiguate your input it is recommeded to map your identifier first (see: mapping). Querying the API with a disambiguated identifier (for example 9606.ENSP00000269305 for human TP53) will guarantee much faster server response.
- Another way to guarantee faster server response is to specify from which species your proteins come from (see 'species' parameter). In fact API will reject queries for networks larger than 10 proteins without the specified organism.
- When developing your tool use default STRING address (https://string-db.org), but when your code is ready, you should link to a specific STRING version (for example "https://version-11-0.string-db.org"), which will ensure that for the same query you will always get the same API response, even after STRING or API gets updated. To see the current STRING version and its URL prefix click here
- STRING understands both GET and POST requests. GET requests, although simpler to use, have a character limit, therefore it is recommended to use POST whenever possible.
- When calling our API from your website or tools please identify yourself using the caller_identity parameter.
Mapping identifiers Top ↑
You can call our STRING API with common gene names, various synonyms or even UniProt identifiers and accession numbers. However, STRING may not always understand them which may lead to errors or inconsistencies. Before using other API methods it is always advantageous to map your identifiers to the ones STRING uses. In addition, STRING will resolve its own identifiers faster, therefore your tool/website will see a speed benefit if you use them. For each input protein STRING places the best matching identifier in the first row, so the first line will usually be the correct one.
Call:
https://string-db.org/api/[output-format]/get_string_ids?identifiers=[your_identifiers]&[optional_parameters]
Available output formats:
| Format | Description |
|---|---|
| tsv | tab separated values, with a header line |
| tsv-no-header | tab separated values, without header line |
| json | JSON format |
| xml | XML format |
Available parameters:
| Parameter | Description |
|---|---|
| identifiers | required parameter for multiple items, e.g. DRD1_HUMAN%0dDRD2_HUMAN |
| echo_query | insert column with your input identifier (takes values '0' or '1', default is '0') |
| limit | limits the number of matches per query identifier (best matches come first) |
| species | NCBI taxon identifiers (e.g. Human is 9606, see: STRING organisms). |
| caller_identity | your identifier for us. |
Output fields:
| Field | Description |
|---|---|
| queryItem | (OPTIONAL) your input protein |
| queryIndex | position of the protein in your input (starting from position 0) |
| stringId | STRING identifier |
| ncbiTaxonId | NCBI taxon identifier |
| taxonName | species name |
| preferredName | common protein name |
| annotation | protein annotation |
Example call (resolving "p53" and "cdk2" in human):
https://string-db.org/api/tsv/get_string_ids?identifiers=p53%0dcdk2&species=9606
Example of python3 code:
#!/usr/bin/env python3
##########################################################
## For a given list of proteins the script resolves them
## (if possible) to the best matching STRING identifier
## and prints out the mapping on screen in the TSV format
##
## Requires requests module:
## type "python -m pip install requests" in command line
## (win) or terminal (mac/linux) to install the module
###########################################################
import requests ## python -m pip install requests
string_api_url = "https://string-db.org/api"
output_format = "tsv-no-header"
method = "get_string_ids"
##
## Set parameters
##
params = {
"identifiers" : "\r".join(["p53", "BRCA1", "cdk2", "Q99835"]), # your protein list
"species" : 9606, # species NCBI identifier
"limit" : 1, # only one (best) identifier per input protein
"echo_query" : 1, # see your input identifiers in the output
"caller_identity" : "www.awesome_app.org" # your app name
}
##
## Construct URL
##
request_url = "/".join([string_api_url, output_format, method])
##
## Call STRING
##
results = requests.post(request_url, data=params)
##
## Read and parse the results
##
for line in results.text.strip().split("\n"):
l = line.split("\t")
input_identifier, string_identifier = l[0], l[2]
print("Input:", input_identifier, "STRING:", string_identifier, sep="\t")
Getting STRING network image Top ↑
With our API you can retrieve an image of a STRING network of a neighborhood surrounding one or more proteins or ask STRING to show only the network of interactions between your input proteins. Both the network flavors (confidence and evidence) and network types (functional and physical) are accessible through the API. The API can output the image as a PNG (low and high resolution with alpha-channel) or as an SVG (vector graphics that can be modified through scripts or in an appropriate software).
Call:
https://string-db.org/api/[output-format]/network?identifiers=[your_identifiers]&[optional_parameters]
Available output formats:
| Format | Description |
|---|---|
| image | network PNG image with alpha-channel |
| highres_image | high resolution network PNG image with alpha-channel |
| svg | vector graphic format (SVG) |
Available parameters:
| Parameter | Description |
|---|---|
| identifiers | required parameter for multiple items, e.g. DRD1_HUMAN%0dDRD2_HUMAN |
| species | NCBI taxon identifiers (e.g. Human is 9606, see: STRING organisms). |
| add_color_nodes | adds color nodes based on scores to the input proteins |
| add_white_nodes | adds white nodes based on scores to the input proteins (added after color nodes) |
| required_score | threshold of significance to include an interaction, a number between 0 and 1000 (default depends on the network) |
| network_flavor | the style of edges in the network: evidence, confidence (default), actions |
| network_type | network type: functional (default), physical |
| hide_node_labels | hides all protein names from the picture (0 or 1) (defailt:0) |
| hide_disconnected_nodes | hides all proteins that are not connected to any other protein in your network (0 or 1) (default:0) |
| show_query_node_labels | when provided use submitted names as protein labels in the network image (0 or 1) (default:0) |
| block_structure_pics_in_bubbles | disables structure pictures inside the bubble (0 or 1) (default:0) |
| caller_identity | your identifier for us. |
If you query the API with one protein the "add_white_nodes" parameter is automatically set to 10, so you can see the interaction neighborhood of your query protein. However, similarly to the STRING webpage, whenever you query the API with more than one protein we show only the interactions between your input proteins. You can, of course, always extend the interaction neighborhood by setting "add_color/white_nodes" parameter to the desired value.
Output (yeast's nuclear pore complex):
Example call (physical interaction neighborhood of nup100 reveals nuclear pore complex):
https://string-db.org/api/image/network?identifiers=nup100&add_color_nodes=10&network_type=physical
Example python3 code:
#!/usr/bin/env python3
################################################################
## For each protein in a list save the PNG image of
## STRING network of its 15 most confident interaction partners.
##
## Requires requests module:
## type "python -m pip install requests" in command line (win)
## or terminal (mac/linux) to install the module
################################################################
import requests ## python -m pip install requests
from time import sleep
string_api_url = "https://string-db.org/api"
output_format = "image"
method = "network"
my_genes = ["YMR055C", "YFR028C",
"YNL161W", "YOR373W",
"YFL009W", "YBR202W"]
##
## Construct URL
##
request_url = "/".join([string_api_url, output_format, method])
## For each gene call STRING
for gene in my_genes:
##
## Set parameters
##
params = {
"identifiers" : gene, # your protein
"species" : 4932, # species NCBI identifier
"add_white_nodes": 15, # add 15 white nodes to my protein
"network_flavor": "confidence", # show confidence links
"caller_identity" : "www.awesome_app.org" # your app name
}
##
## Call STRING
##
response = requests.post(request_url, data=params)
##
## Save the network to file
##
file_name = "%s_network.png" % gene
print("Saving interaction network to %s" % file_name)
with open(file_name, 'wb') as fh:
fh.write(response.content)
sleep(1)
Linking to the network on STRING webpage Top ↑
This API allows you to get a link to your network on the STRING webapge. The parameters are the same as retrieving the network through other API methods (as a image or as a text file) and the produced networks will be the same. Generated link is a "stable" one which means it will redirect to the specific STRING version (if not specified with the url prefix, it will link to the current version of STRING).
Call:
https://string-db.org/api/[output-format]/get_link?identifiers=[your_identifiers]&[optional_parameters]
Available output formats:
| Format | Description |
|---|---|
| tsv | tab separated values, with a header line |
| tsv-no-header | tab separated values, without header line |
| json | JSON format |
| xml | XML format |
Available parameters:
| Parameter | Description |
|---|---|
| identifiers | required parameter for multiple items, e.g. DRD1_HUMAN%0dDRD2_HUMAN |
| species | NCBI taxon identifiers (e.g. Human is 9606, see: STRING organisms). |
| add_color_nodes | adds color nodes based on scores to the input proteins |
| add_white_nodes | adds white nodes based on scores to the input proteins (added after color nodes) |
| required_score | threshold of significance to include an interaction, a number between 0 and 1000 (default depends on the network) |
| network_flavor | the style of edges in the network: evidence, confidence (default), actions |
| network_type | network type: functional (default), physical |
| hide_node_labels | hides all protein names from the picture (0 or 1) (defailt:0) |
| hide_disconnected_nodes | hides all proteins that are not connected to any other protein in your network (0 or 1) (default:0) |
| show_query_node_labels | when provided use submitted names as protein labels in the network image (0 or 1) (default:0) |
| block_structure_pics_in_bubbles | disables structure pictures inside the bubble (0 or 1) (default:0) |
| caller_identity | your identifier for us. |
If you query the API with one protein the "add_color_nodes" parameter is automatically set to 10. Whenever you query the API with more than one protein we show only the interactions between your input proteins. You can, of course, always extend the interaction neighborhood by setting "add_color/white_nodes" parameter to the desired value.
Output fields:
| Field | Description |
|---|---|
| url | stable link to the network |
Example call (Link to Drosophila's smoothened protein interaction neighborhood):
https://string-db.org/api/tsv/get_link?identifiers=SMO&species=7227
Embedding the interactive network Top ↑
Using provided simple HTML and JavaScript code you can embed the interactive STRING network in your website or webApp. The advantages of the interactive network are several: 1) The user can move the nodes around to explore the network's structure 2) each node can be clicked and a pop-up will appear above the network providing information about the protein's structure, its function and sequence 3) the network contains a link-out to STRING that lets the user jump directly to STRING website and explore interactions in even more details. The behaviour of the API is similar to the Getting the network image API, that is, it lets you retrieve either 1) the image of the interaction neighborhood of one or more proteins and 2) the image of the interaction network only between the specified set of proteins. The two APIs also shares the exact same set of parametes.
Code:
First your website has to load two elements to make it work. IMPORTANT: Do not load these elements in the iFrame - if you do the pop-ups will be confiened only to the iFrame instead of overlaying your website.
The first element is a small STRING's javascript library that allows for moveable bubbles and pop-ups.
<script type="text/javascript" src="http://string-db.org/javascript/combined_embedded_network_v2.0.2.js"></script>
The second is an HTML DIV element. You insert in the place where you want the network to displayed. You can assign any class to this element or style it however you want, just do not change its identifier.
<div id="stringEmbedded"></div>
And finally this API call in Javascript:
getSTRING('https://string-db.org', {[dictionary of parameters]})">
Available parameters:
| Parameter | Description |
|---|---|
| identifiers | required parameter - array of protein names e.g. ['TP53', 'CDK2'] |
| species | NCBI taxon identifiers (e.g. Human is 9606, see: STRING organisms). |
| add_color_nodes | adds color nodes based on scores to the input proteins |
| add_white_nodes | adds white nodes based on scores to the input proteins (added after color nodes) |
| required_score | threshold of significance to include an interaction, a number between 0 and 1000 (default depends on the network) |
| network_flavor | the style of edges in the network: evidence, confidence (default), actions |
| network_type | network type: functional (default), physical |
| hide_node_labels | hides all protein names from the picture (0 or 1) (defailt:0) |
| hide_disconnected_nodes | hides all proteins that are not connected to any other protein in your network (0 or 1) (default:0) |
| show_query_node_labels | when provided use submitted names as protein labels in the network image (0 or 1) (default:0) |
| block_structure_pics_in_bubbles | disables structure pictures inside the bubble (0 or 1) (default:0) |
| caller_identity | your identifier for us. |
Example JavaScript call (TP53 interaction neighborhood):
getSTRING('https://string-db.org', {'species':'9606', 'identifiers':['TP53'], 'network_flavor':'confidence'})">
Example website code (to test it copy paste it into an empty file with .html extenstion and open it in your browser):
<!DOCTYPE html>
<html>
<head>
<!-- Embed the STRING's javascript -->
<script type="text/javascript" src="https://string-db.org/javascript/combined_embedded_network_v2.0.2.js"></script>
<style>
/* some styling */
body {
font-family: Arial;
color: #122e4d;
background: #cedded;
}
input {
border: 4px solid #122e4d;
width: 40%;
height: 50px;
border-radius: 10px;
font-size: 20px;
}
button {
font-size:20px;
border-radius: 10px;
border: 1px solid #122e4d;
}
</style>
<script>
function send_request_to_string() {
var inputField = document.getElementById('inputarea');
var text = inputField.value;
if (!text) {text = inputField.placeholder}; // placeholder
var proteins = text.split(' ');
/* the actual API query */
getSTRING('https://string-db.org', {
'species':'9606',
'identifiers':proteins,
'network_flavor':'confidence',
'caller_identity': 'www.awesome_app.org'
})
}
</script>
</head>
<!-- HTML CODE -->
<body onload='javascript:send_request_to_string()'>
<center>
<h1>YOUR WEBSITE</h1>
<h3>Query me: (one human protein or multiple space seperated proteins)</h3>
<input type="text" id='inputarea' placeholder='GLI3'><br/></br/>
<button onclick='javascript:send_request_to_string();' type="button">Let's go!</button>
<h3>Network:</h3>
<div id="stringEmbedded"></div>
</center>
</body>
</html>
Getting the STRING network interactions Top ↑
The network API method also allows you to retrieve your STRING interaction network for one or multiple proteins in various text formats. It will tell you the combined score and all the channel specific scores for the set of proteins. You can also extend the network neighborhood by setting "add_nodes", which will add, to your network, new interaction partners in order of their confidence.
Call:
https://string-db.org/api/[output-format]/network?identifiers=[your_identifiers]&[optional_parameters]
Available output formats:
| Format | Description |
|---|---|
| tsv | tab separated values, with a header line |
| tsv-no-header | tab separated values, without header line |
| json | JSON format |
| xml | XML format |
| psi-mi | PSI-MI XML format |
| psi-mi-tab | PSI-MITAB format |
Available parameters:
| Parameter | Description |
|---|---|
| identifiers | required parameter for multiple items, e.g. DRD1_HUMAN%0dDRD2_HUMAN |
| species | NCBI taxon identifiers (e.g. Human is 9606, see: STRING organisms). |
| required_score | threshold of significance to include a interaction, a number between 0 and 1000 (default depends on the network) |
| network_type | network type: functional (default), physical |
| add_nodes | adds a number of proteins with to the network based on their confidence score |
| show_query_node_labels | when available use submitted names in the preferredName column when (0 or 1) (default:0) |
| caller_identity | your identifier for us. |
If you query the API with one protein the "add_nodes" parameter is automatically set to 10, so you can can get the interaction neighborhood of your query protein. However, similarly to the STRING webpage, whenever you query the API with more than one protein the method will output only the interactions between your input proteins. You can, of course, always extend the interaction neighborhood by setting "add_nodes" parameter to the desired value.
Output fields (TSV and JSON formats):
| Field | Description |
|---|---|
| stringId_A | STRING identifier (protein A) |
| stringId_B | STRING identifier (protein B) |
| preferredName_A | common protein name (protein A) |
| preferredName_B | common protein name (protein B) |
| ncbiTaxonId | NCBI taxon identifier |
| score | combined score |
| nscore | gene neighborhood score |
| fscore | gene fusion score |
| pscore | phylogenetic profile score |
| ascore | coexpression score |
| escore | experimental score |
| dscore | database score |
| tscore | textmining score |
To see how the combined score is computed from the partial scores see FAQ
Example call (retrieve all interactions between TP53 EGFR and CDK2):
https://string-db.org/api/tsv/network?identifiers=TP53%0dEGFR%0dCDK2&required_score=400
Example python3 code:
#!/usr/bin/env python3
##################################################################
## For the given list of proteins print out only the interactions
## between these protein which have medium or higher confidence
## experimental score
##
## Requires requests module:
## type "python -m pip install requests" in command line (win)
## or terminal (mac/linux) to install the module
##################################################################
import requests ## python -m pip install requests
string_api_url = "https://string-db.org/api"
output_format = "tsv-no-header"
method = "network"
##
## Construct URL
##
request_url = "/".join([string_api_url, output_format, method])
##
## Set parameters
##
my_genes = ["CDC42","CDK1","KIF23","PLK1",
"RAC2","RACGAP1","RHOA","RHOB"]
params = {
"identifiers" : "%0d".join(my_genes), # your protein
"species" : 9606, # species NCBI identifier
"caller_identity" : "www.awesome_app.org" # your app name
}
##
## Call STRING
##
response = requests.post(request_url, data=params)
for line in response.text.strip().split("\n"):
l = line.strip().split("\t")
p1, p2 = l[2], l[3]
## filter the interaction according to experimental score
experimental_score = float(l[10])
if experimental_score > 0.4:
## print
print("\t".join([p1, p2, "experimentally confirmed (prob. %.3f)" % experimental_score]))
Getting all the STRING interaction partners of the protein set Top ↑
Diffrently from the network API method, which retrieves only the interactions between the set of input proteins and between their closest interaction neighborhood (if add_nodes parameters is specified), interaction_partners API method provides the interactions between your set of proteins and all the other STRING proteins. The output is available in various text based formats. As STRING network usually has a lot of low scoring interactions, you may want to limit the number of retrieved interaction per protein using "limit" parameter (of course the high scoring interactions will come first).
Call:
https://string-db.org/api/[output-format]/interaction_partners?identifiers=[your_identifiers]&[optional_parameters]
Available output formats:
| Format | Description |
|---|---|
| tsv | tab separated values, with a header line |
| tsv-no-header | tab separated values, without header line |
| json | JSON format |
| xml | XML format |
| psi-mi | PSI-MI XML format |
| psi-mi-tab | PSI-MITAB format |
Available parameters:
| Parameter | Description |
|---|---|
| identifiers | required parameter for multiple items, e.g. DRD1_HUMAN%0dDRD2_HUMAN |
| species | NCBI taxon identifiers (e.g. Human is 9606, see: STRING organisms). |
| limit | limits the number of interaction partners retrieved per protein (most confident interactions come first) |
| required_score | threshold of significance to include a interaction, a number between 0 and 1000 (default depends on the network) |
| network_type | network type: functional (default), physical |
| caller_identity | your identifier for us. |
Output fields (TSV and JSON formats):
| Field | Description |
|---|---|
| stringId_A | STRING identifier (protein A) |
| stringId_B | STRING identifier (protein B) |
| preferredName_A | common protein name (protein A) |
| preferredName_B | common protein name (protein B) |
| ncbiTaxonId | NCBI taxon identifier |
| score | combined score |
| nscore | gene neighborhood score |
| fscore | gene fusion score |
| pscore | phylogenetic profile score |
| ascore | coexpression score |
| escore | experimental score |
| dscore | database score |
| tscore | textmining score |
To see how the combined score is computed from the partial scores see FAQ
Example call (retrieve best 10 STRING interactions for TP53 and CDK2):
https://string-db.org/api/tsv/interaction_partners?identifiers=TP53%0dCDK2&limit=10
Example python3 code:
#!/usr/bin/env python3
################################################################
## For each protein in the given list print the names of
## their 5 best interaction partners.
##
## Requires requests module:
## type "python -m pip install requests" in command line (win)
## or terminal (mac/linux) to install the module
################################################################
import requests ## python -m pip install requests
string_api_url = "https://string-db.org/api"
output_format = "tsv-no-header"
method = "interaction_partners"
my_genes = ["9606.ENSP00000000233", "9606.ENSP00000000412",
"9606.ENSP00000000442", "9606.ENSP00000001008"]
##
## Construct the request
##
request_url = "/".join([string_api_url, output_format, method])
##
## Set parameters
##
params = {
"identifiers" : "%0d".join(my_genes), # your protein
"species" : 9606, # species NCBI identifier
"limit" : 5,
"caller_identity" : "www.awesome_app.org" # your app name
}
##
## Call STRING
##
response = requests.post(request_url, data=params)
##
## Read and parse the results
##
for line in response.text.strip().split("\n"):
l = line.strip().split("\t")
query_ensp = l[0]
query_name = l[2]
partner_ensp = l[1]
partner_name = l[3]
combined_score = l[5]
## print
print("\t".join([query_ensp, query_name, partner_name, combined_score]))
Retrieving similarity scores of the protein set Top ↑
STRING internally uses the Smith–Waterman bit scores as a proxy for protein homology. The original scores are computed by SIMILARITY MATRIX OF PROTEINS (SIMAP) project. Using this API you can retrieve these scores between the proteins in a selected species. They are symmetric, therefore to make the transfer a bit faster we will send only half of the similarity matrix (A->B, but not symmetric B->A) and the self-hits. The bit score cut-off below which we do not store or report homology is 50.
Call:
https://string-db.org/api/[output-format]/homology?identifiers=[your_identifiers]
Available output formats:
| Format | Description |
|---|---|
| tsv | tab separated values, with a header line |
| tsv-no-header | tab separated values, without header line |
| json | JSON format |
| xml | XML format |
Available parameters:
| Parameter | Description |
|---|---|
| identifiers | required parameter for multiple items, e.g. DRD1_HUMAN%0dDRD2_HUMAN |
| species | NCBI taxon identifiers (e.g. Human is 9606, see: STRING organisms). |
| caller_identity | your identifier for us. |
Output fields (TSV and JSON formats):
| Field | Description |
|---|---|
| ncbiTaxonId_A | NCBI taxon identifier (protein A) |
| stringId_A | STRING identifier (protein A) |
| ncbiTaxonId_B | NCBI taxon identifier (protein B) |
| stringId_B | STRING identifier (protein B) |
| bitscore | Smith-Waterman alignment bit score |
Example call (retrieve homology scores between CDK1 and CDK2)
https://string-db.org/api/tsv/homology?identifiers=CDK1%0dCDK2
Retrieving best similarity hits between species Top ↑
STRING internally uses the Smith–Waterman bit scores as a proxy for protein homology. The original scores are computed by SIMILARITY MATRIX OF PROTEINS (SIMAP) project. Using this API you can retrieve these similarity scores between your input proteins and proteins in all of the STRING's organisms. Only the best hit per organism for each protein will be retrieved.
There are many organisms in STRING, so expect thousands hits for each protein, however you can filter the results to the list of organisms of interest by using 'species_b' parameter.
Call:
https://string-db.org/api/[output-format]/homology_best?identifiers=[your_identifiers]
Available output formats:
| Format | Description |
|---|---|
| tsv | tab separated values, with a header line |
| tsv-no-header | tab separated values, without header line |
| json | JSON format |
| xml | XML format |
Available parameters:
| Parameter | Description |
|---|---|
| identifiers | required parameter for multiple items, e.g. DRD1_HUMAN%0dDRD2_HUMAN |
| species | NCBI taxon identifiers (e.g. Human is 9606, see: STRING organisms). |
| species_b | a list of NCBI taxon identifiers seperated by "%0d" (e.g. human, fly and yeast would be "9606%0d7227%0d4932" see: STRING organisms). |
| caller_identity | your identifier for us. |
Output fields (TSV and JSON formats):
| Field | Description |
|---|---|
| ncbiTaxonId_A | NCBI taxon identifier (protein A) |
| stringId_A | STRING identifier (protein A) |
| ncbiTaxonId_B | NCBI taxon identifier (protein B) |
| stringId_B | STRING identifier (protein B) |
| bitscore | Smith-Waterman alignment bit score |
Example call (retrieve best homology score between human CDK1 and its closest mouse homolog)
https://string-db.org/api/tsv/homology_best?identifiers=CDK1&species_b=10090
Getting functional enrichment Top ↑
STRING maps several databases onto its proteins, this includes: Gene Ontology, KEGG pathways, UniProt Keywords, PubMed publications, Pfam domains, InterPro domains, and SMART domains.The STRING enrichment API method allows you to retrieve functional enrichment for any set of input proteins. It will tell you which of your input proteins have an enriched term and the term's description. The API provides the raw p-values, as well as, False Discovery Rate and Bonferroni corrected p-values. The detailed description of the enrichment algorithm can be found here
Call:
https://string-db.org/api/[output_format]/enrichment?identifiers=[your_identifiers]&[optional_parameters]
Available output formats:
| Format | Description |
|---|---|
| tsv | tab separated values, with a header line |
| tsv-no-header | tab separated values, without header line |
| json | JSON format |
| xml | XML format |
Available parameters:
| Parameter | Description |
|---|---|
| identifiers | required parameter for multiple items, e.g. DRD1_HUMAN%0dDRD2_HUMAN |
| background_string_identifiers | using this parameter you can specify the background proteome of your experiment. Only STRING identifiers will be recognised (each must be seperated by "%0d") e.g. '7227.FBpp0077451%0d7227.FBpp0074373'. You can map STRING identifiers using mapping identifiers method. |
| species | NCBI taxon identifiers (e.g. Human is 9606, see: STRING organisms). |
| caller_identity | your identifier for us. |
Output fields:
| Field | Description |
|---|---|
| category | term category (e.g. GO Process, KEGG pathways) |
| term | enriched term (GO term, domain or pathway) |
| number_of_genes | number of genes in your input list with the term assigned |
| number_of_genes_in_background | total number of genes in the background proteome with the term assigned |
| ncbiTaxonId | NCBI taxon identifier |
| inputGenes | gene names from your input |
| preferredNames | common protein names (in the same order as your input Genes) |
| p_value | raw p-value |
| fdr | False Discovery Rate |
| description | description of the enriched term |
STRING shows only the terms with the raw p-value below 0.1
Example call (the network neighborhood of Epidermal growth factor receptor):
https://string-db.org/api/tsv/enrichment?identifiers=trpA%0dtrpB%0dtrpC%0dtrpE%0dtrpGD
Example python3 code:
#!/usr/bin/env python3
##############################################################
## The following script retrieves and prints out
## significantly enriched (FDR < 1%) GO Processes
## for the given set of proteins.
##
## Requires requests module:
## type "python -m pip install requests" in command line (win)
## or terminal (mac/linux) to install the module
##############################################################
import requests ## python -m pip install requests
import json
string_api_url = "https://string-db.org/api"
output_format = "json"
method = "enrichment"
##
## Construct the request
##
request_url = "/".join([string_api_url, output_format, method])
##
## Set parameters
##
my_genes = ['7227.FBpp0074373', '7227.FBpp0077451', '7227.FBpp0077788',
'7227.FBpp0078993', '7227.FBpp0079060', '7227.FBpp0079448']
params = {
"identifiers" : "%0d".join(my_genes), # your protein
"species" : 7227, # species NCBI identifier
"caller_identity" : "www.awesome_app.org" # your app name
}
##
## Call STRING
##
response = requests.post(request_url, data=params)
##
## Read and parse the results
##
data = json.loads(response.text)
for row in data:
term = row["term"]
preferred_names = ",".join(row["preferredNames"])
fdr = float(row["fdr"])
description = row["description"]
category = row["category"]
if category == "Process" and fdr < 0.01:
## print significant GO Process annotations
print("\t".join([term, preferred_names, str(fdr), description]))
Retrieving functional annotation Top ↑
STRING maps several databases onto its proteins, this includes: Gene Ontology, KEGG pathways, UniProt Keywords, PubMed publications, Pfam domains, InterPro domains, and SMART domains. You can retrieve all these annotations (and not only enriched subset) for your proteins via this API. Due to the potential large size of the PubMed (Reference Publications) assignments, they won't be sent by default, but you can turn them back on by specifying the 'allow_pubmed=1' parameter.
Please note: KEGG annotations are not available due to KEGG licence restrictions.
Call:
https://string-db.org/api/[output_format]/functional_annotation?identifiers=[your_identifiers]&[optional_parameters]
Available output formats:
| Format | Description |
|---|---|
| tsv | tab separated values, with a header line |
| tsv-no-header | tab separated values, without header line |
| json | JSON format |
| xml | XML format |
Available parameters:
| Parameter | Description |
|---|---|
| identifiers | required parameter for multiple items, e.g. DRD1_HUMAN%0dDRD2_HUMAN |
| species | NCBI taxon identifiers (e.g. Human is 9606, see: STRING organisms). |
| allow_pubmed | '1' to print also the PubMed annotations, default is '0' |
| caller_identity | your identifier for us. |
Output fields:
| Field | Description |
|---|---|
| category | term category (e.g. GO Process, KEGG pathways) |
| term | enriched term (GO term, domain or pathway) |
| number_of_genes | number of genes in your input list with the term assigned |
| ratio_in_set | ratio of the proteins in your input list with the term assigned |
| ncbiTaxonId | NCBI taxon identifier |
| inputGenes | gene names from your input |
| preferredNames | common protein names (in the same order as your input Genes) |
| description | description of the enriched term |
Example call (the network neighborhood of Epidermal growth factor receptor):
https://string-db.org/api/tsv/functional_annotation?identifiers=cdk1
Getting protein-protein interaction enrichment Top ↑
Even in the absence of annotated proteins (e.g. in novel genomes) STRING can tell you if your subset of proteins is functionally related, that is, if it is enriched in interactions in comparison to the background proteome-wide interaction distribution. The detailed description of the PPI enrichment method can be found here
Call:
https://string-db.org/api/[output_format]/ppi_enrichment?identifiers=[your_identifiers]&[optional_parameters]
Available output formats:
| Format | Description |
|---|---|
| tsv | tab separated values, with a header line |
| tsv-no-header | tab separated values, without header line |
| json | JSON format |
| xml | XML format |
Available parameters:
| Parameter | Description |
|---|---|
| identifiers | required parameter for multiple items, e.g. DRD1_HUMAN%0dDRD2_HUMAN |
| species | NCBI taxon identifiers (e.g. Human is 9606, see: STRING organisms). |
| required_score | threshold of significance to include a interaction, a number between 0 and 1000 (default depends on the network) |
| caller_identity | your identifier for us. |
Output fields:
| Field | Description |
|---|---|
| number_of_nodes | number of proteins in your network |
| number_of_edges | number of edges in your network |
| average_node_degree | mean degree of the node in your network |
| local_clustering_coefficient | average local clustering coefficient |
| expected_number_of_edges | expected number of edges based on the nodes degrees |
| p_value | significance of your network having more interactions than expected |
Example call (the network neighborhood of Epidermal growth factor receptor):
https://string-db.org/api/tsv/ppi_enrichment?identifiers=trpA%0dtrpB%0dtrpC%0dtrpE%0dtrpGD
Example python3 code:
#!/usr/bin/env python
##############################################################
## The script prints out the p-value of STRING protein-protein
## interaction enrichment method for the given set of proteins
##
## Requires requests module:
## type "python -m pip install requests" in command line (win)
## or terminal (mac/linux) to install the module
##############################################################
import requests ## python -m pip install requests
string_api_url = "https://string-db.org/api"
output_format = "tsv-no-header"
method = "ppi_enrichment"
##
## Construct the request
##
request_url = "/".join([string_api_url, output_format, method])
##
## Set parameters
##
my_genes = ['7227.FBpp0074373', '7227.FBpp0077451', '7227.FBpp0077788',
'7227.FBpp0078993', '7227.FBpp0079060', '7227.FBpp0079448']
params = {
"identifiers" : "%0d".join(my_genes), # your proteins
"species" : 7227, # species NCBI identifier
"caller_identity" : "www.awesome_app.org" # your app name
}
##
## Call STRING
##
response = requests.post(request_url, data=params)
##
## Parse and print the respons Parse and print the responsee
##
for line in response.text.strip().split("\n"):
pvalue = line.split("\t")[5]
print("P-value:", pvalue)
Getting current STRING version Top ↑
STRING is not updated, on average, every two years. Maybe you would like to download the latest version of STRING's genomes, or simply you would like to be informed if the new version is released. For this you can use the version API, which tell you the latest version of STRING and its stable address. The 'stable address' is an address that does not change beteween version, so if you use the stable API address it will always produce the results from that particular version.
Call:
https://string-db.org/api/[output_format]/version
Available output formats:
| Format | Description |
|---|---|
| tsv | tab separated values, with a header line |
| tsv-no-header | tab separated values, without header line |
| json | JSON format |
| xml | XML format |
Available parameters:
None
Output fields:
| Field | Description |
|---|---|
| string_version | current string version |
| string_stable_address | STRING stable url |
Example call:
https://string-db.org/api/json/version
Additional information about the API Top ↑
If you need to do a large-scale analysis, please download the full data set. Otherwise you may end up fooding the STRING server with API requests. In particular, try to avoid running scripts in parallel :)
Please contact us if you have any questions regarding the API.
API for retrieving abstracts and actions is temporary undocumented but will return soon in a revised form.