How to use SmallWorld API: Difference between revisions
Jgutierrez6 (talk | contribs) mNo edit summary |
Jgutierrez6 (talk | contribs) mNo edit summary |
||
| Line 1: | Line 1: | ||
=Introduction= | ==Introduction== | ||
The Web Services API for SmallWorld Documentation is found in Section | The Web Services API for SmallWorld Documentation is found in Section 6.3 of the SmallWorld version 5.6.2 manual. | ||
Here are some simple examples. | Here are some simple examples. | ||
== | ==API Routes== | ||
===/search/maps=== | |||
List all available databases (map files). | |||
<source>curl -X GET "https://sw.docking.org/search/maps"</source> | |||
===/search/view=== | |||
===/search/submit=== | ===/search/submit=== | ||
| Line 66: | Line 72: | ||
Everything else can stay the same | Everything else can stay the same | ||
curl https://sw.docking.org/search/submit?smi=c1ccccc1&db=ZINC20-ForSale-22Q1-1.6B&dist=4&tdn=4&tup=4&rdn=4&rup=4&ldn=4&lup=4&maj=4&min=4&sub=4&scores=Atom%20Alignment,ECFP4,Daylight | curl 'https://sw.docking.org/search/submit?smi=c1ccccc1&db=ZINC20-ForSale-22Q1-1.6B&dist=4&tdn=4&tup=4&rdn=4&rup=4&ldn=4&lup=4&maj=4&min=4&sub=4&scores=Atom%20Alignment,ECFP4,Daylight' | ||
The API streams back JSON chunks. Possible status messages are FIRST, MORE, END, and ‘Ground Control to Major Tom’ (hangup ping). Each status contains the hit list id (hlid) which can be used with the export and view API entry points. | The API streams back JSON chunks. Possible status messages are FIRST, MORE, END, and ‘Ground Control to Major Tom’ (hangup ping). Each status contains the hit list id (hlid) which can be used with the export and view API entry points. | ||
Revision as of 22:46, 17 January 2024
Introduction
The Web Services API for SmallWorld Documentation is found in Section 6.3 of the SmallWorld version 5.6.2 manual.
Here are some simple examples.
API Routes
/search/maps
List all available databases (map files).
curl -X GET "https://sw.docking.org/search/maps"/search/view
/search/submit
Start a new SmallWorld search with topological distance bounded by the provided upper bounds.
| Parameter | Type | Description |
|---|---|---|
| smi | text | Query SMILES |
| db | text | Reference database (see List of available maps) |
| dist | int | Topological distance upper bound (default: 10) |
| tdn | int | Topological terminal down distance upper bound (default: 10) |
| tup | int | Topological terminal up distance upper bound (default: 10) |
| rdn | int | Topological ring down distance upper bound (default: 10) |
| rup | int | Topological ring up distance upper bound (default: 10) |
| ldn | int | Topological linker down distance upper bound (default: 10) |
| lup | int | Topological linker up distance upper bound (default: 10) |
| scores | text | List of scoring functions (default : none) - see /search/config |
Example Request
Suppose you want to search for c1ccccc1 in the ZINC-Interesting-297K Database: There are two steps. The first step which involves /search/submit returns a stream of events that report the hit list id or hlid. This hlid is required to fetch results using the other options such as /search/view
- Change the smi to the SMILES for the molecule you want to query
- Change the db name to the database name from the List of Publicly Available Maps below
Everything else can stay the same
curl 'https://sw.docking.org/search/submit?smi=c1ccccc1&db=ZINC20-ForSale-22Q1-1.6B&dist=4&tdn=4&tup=4&rdn=4&rup=4&ldn=4&lup=4&maj=4&min=4&sub=4&scores=Atom%20Alignment,ECFP4,Daylight'
The API streams back JSON chunks. Possible status messages are FIRST, MORE, END, and ‘Ground Control to Major Tom’ (hangup ping). Each status contains the hit list id (hlid) which can be used with the export and view API entry points.
From this example:
data:{"status":"FIRST","hlid":4,"elap":"0.0 s","numEdges":0,"numNodes":0,"numWaveFront":0,"numEdgesPerSec":"NaN"}
data:{"status":"MORE","hlid":4,"elap":"0.0 s","numEdges":1,"numNodes":2,"numWaveFront":6,"numEdgesPerSec":235.13693552145494}
data:{"status":"MORE","hlid":4,"elap":"0.0 s","numEdges":7,"numNodes":8,"numWaveFront":20,"numEdgesPerSec":627.698881010172}
data:{"status":"MORE","hlid":4,"elap":"0.0 s","numEdges":47,"numNodes":42,"numWaveFront":57,"numEdgesPerSec":1398.0183120172226}
data:{"status":"MORE","hlid":4,"elap":"0.1 s","numEdges":361,"numNodes":215,"numWaveFront":218,"numEdgesPerSec":3172.39634840835}
data:{"status":"Ground Control to Major Tom","hlid":4,"elap":"0.3 s","numEdges":1358,"numNodes":661,"numWaveFront":104,"numEdgesPerSec":4439.029279091838}
data:{"status":"END","hlid":4,"elap":"0.5 s","numEdges":2417,"numNodes":981,"numWaveFront":0,"numEdgesPerSec":4984.08672048595}Here the hlid for my request was 4.
/search/export
Export a hit list (given by the id) to a tab-separated value table. The other parameters describe what columns, order, and filters are applied to the hit list. Like /search/view it uses the JQuery DataTables server-side processing parameters - https://www.datatables.net/manual/server-side.
Useful information about column names and values: 'hlid': hlid,
'columns[0][data]': 0, 'columns[0][name]': 'alignment', 'columns[0][searchable]': 'true', 'columns[0][orderable]': 'false', 'columns[0][search][value]': , 'columns[0][search][regex]': 'false',
'columns[1][data]': 1, 'columns[1][name]': 'dist', 'columns[1][searchable]': 'true', 'columns[1][orderable]': 'true', 'columns[1][search][value]': '0 - 10', 'columns[1][search][regex]': 'false',
'columns[2][data]': 2, 'columns[2][name]': 'ecfp4', 'columns[2][searchable]': 'true', 'columns[2][orderable]': 'true', 'columns[2][search][value]': , 'columns[2][search][regex]': 'false',
'columns[3][data]': 3, 'columns[3][name]': 'daylight', 'columns[3][searchable]': 'true', 'columns[3][orderable]': 'true', 'columns[3][search][value]': , 'columns[3][search][regex]': 'false',
'columns[4][data]': 4, 'columns[4][name]': 'topodist', 'columns[4][searchable]': 'true', 'columns[4][orderable]': 'true', 'columns[4][search][value]': '0 - 10', 'columns[4][search][regex]': 'false',
'columns[5][data]': 5, 'columns[5][name]': 'mces', 'columns[5][searchable]': 'true', 'columns[5][orderable]': 'true', 'columns[5][search][value]': , 'columns[5][search][regex]': 'false',
'columns[6][data]': 6, 'columns[6][name]': 'tdn', 'columns[6][searchable]': 'true', 'columns[6][orderable]': 'true', 'columns[6][search][value]': '0 - 0', 'columns[6][search][regex]': 'false',
'columns[7][data]': 7, 'columns[7][name]': 'tup', 'columns[7][searchable]': 'true', 'columns[7][orderable]': 'true', 'columns[7][search][value]': '0 - 10', 'columns[7][search][regex]': 'false',
'columns[8][data]': 8, 'columns[8][name]': 'rdn', 'columns[8][searchable]': 'true', 'columns[8][orderable]': 'true', 'columns[8][search][value]': '0 - 0', 'columns[8][search][regex]': 'false',
'columns[9][data]': 9, 'columns[9][name]': 'rup', 'columns[9][searchable]': 'true', 'columns[9][orderable]': 'true', 'columns[9][search][value]': '0 - 10', 'columns[9][search][regex]': 'false',
'columns[10][data]': 10, 'columns[10][name]': 'ldn', 'columns[10][searchable]': 'true', 'columns[10][orderable]':
Important! Once you run the /search/submit the most important value is the hlid
The columns in the resulting tab separated file are alignment dist ecfp4 daylight topodist mces tdn tup rdn rup ldn lup mut maj min hyb sub The results are sorted in starting with the highest ECFP4
Example Request
- Here you only need to change the hlid!
curl 'https://sw.docking.org//search/export/?hlid=4&draw=8&columns%5B0%5D%5Bdata%5D=0&columns%5B0%5D%5Bname%5D=alignment&columns%5B0%5D%5Bsearchable%5D=true&columns%5B0%5D%5Borderable%5D=false&columns%5B0%5D%5Bsearch%5D%5Bvalue%5D=&columns%5B0%5D%5Bsearch%5D%5Bregex%5D=false&columns%5B1%5D%5Bdata%5D=1&columns%5B1%5D%5Bname%5D=dist&columns%5B1%5D%5Bsearchable%5D=true&columns%5B1%5D%5Borderable%5D=true&columns%5B1%5D%5Bsearch%5D%5Bvalue%5D=0-10&columns%5B1%5D%5Bsearch%5D%5Bregex%5D=false&columns%5B2%5D%5Bdata%5D=2&columns%5B2%5D%5Bname%5D=ecfp4&columns%5B2%5D%5Bsearchable%5D=true&columns%5B2%5D%5Borderable%5D=true&columns%5B2%5D%5Bsearch%5D%5Bvalue%5D=&columns%5B2%5D%5Bsearch%5D%5Bregex%5D=false&columns%5B3%5D%5Bdata%5D=3&columns%5B3%5D%5Bname%5D=daylight&columns%5B3%5D%5Bsearchable%5D=true&columns%5B3%5D%5Borderable%5D=true&columns%5B3%5D%5Bsearch%5D%5Bvalue%5D=&columns%5B3%5D%5Bsearch%5D%5Bregex%5D=false&columns%5B4%5D%5Bdata%5D=4&columns%5B4%5D%5Bname%5D=topodist&columns%5B4%5D%5Bsearchable%5D=true&columns%5B4%5D%5Borderable%5D=true&columns%5B4%5D%5Bsearch%5D%5Bvalue%5D=0-4&columns%5B4%5D%5Bsearch%5D%5Bregex%5D=false&columns%5B5%5D%5Bdata%5D=5&columns%5B5%5D%5Bname%5D=mces&columns%5B5%5D%5Bsearchable%5D=true&columns%5B5%5D%5Borderable%5D=true&columns%5B5%5D%5Bsearch%5D%5Bvalue%5D=&columns%5B5%5D%5Bsearch%5D%5Bregex%5D=false&columns%5B6%5D%5Bdata%5D=6&columns%5B6%5D%5Bname%5D=tdn&columns%5B6%5D%5Bsearchable%5D=true&columns%5B6%5D%5Borderable%5D=true&columns%5B6%5D%5Bsearch%5D%5Bvalue%5D=0-4&columns%5B6%5D%5Bsearch%5D%5Bregex%5D=false&columns%5B7%5D%5Bdata%5D=7&columns%5B7%5D%5Bname%5D=tup&columns%5B7%5D%5Bsearchable%5D=true&columns%5B7%5D%5Borderable%5D=true&columns%5B7%5D%5Bsearch%5D%5Bvalue%5D=0-4&columns%5B7%5D%5Bsearch%5D%5Bregex%5D=false&columns%5B8%5D%5Bdata%5D=8&columns%5B8%5D%5Bname%5D=rdn&columns%5B8%5D%5Bsearchable%5D=true&columns%5B8%5D%5Borderable%5D=true&columns%5B8%5D%5Bsearch%5D%5Bvalue%5D=0-4&columns%5B8%5D%5Bsearch%5D%5Bregex%5D=false&columns%5B9%5D%5Bdata%5D=9&columns%5B9%5D%5Bname%5D=rup&columns%5B9%5D%5Bsearchable%5D=true&columns%5B9%5D%5Borderable%5D=true&columns%5B9%5D%5Bsearch%5D%5Bvalue%5D=0-4&columns%5B9%5D%5Bsearch%5D%5Bregex%5D=false&columns%5B10%5D%5Bdata%5D=10&columns%5B10%5D%5Bname%5D=ldn&columns%5B10%5D%5Bsearchable%5D=true&columns%5B10%5D%5Borderable%5D=true&columns%5B10%5D%5Bsearch%5D%5Bvalue%5D=0-4&columns%5B10%5D%5Bsearch%5D%5Bregex%5D=false&columns%5B11%5D%5Bdata%5D=11&columns%5B11%5D%5Bname%5D=lup&columns%5B11%5D%5Bsearchable%5D=true&columns%5B11%5D%5Borderable%5D=true&columns%5B11%5D%5Bsearch%5D%5Bvalue%5D=0-4&columns%5B11%5D%5Bsearch%5D%5Bregex%5D=false&columns%5B12%5D%5Bdata%5D=12&columns%5B12%5D%5Bname%5D=mut&columns%5B12%5D%5Bsearchable%5D=true&columns%5B12%5D%5Borderable%5D=true&columns%5B12%5D%5Bsearch%5D%5Bvalue%5D=&columns%5B12%5D%5Bsearch%5D%5Bregex%5D=false&columns%5B13%5D%5Bdata%5D=13&columns%5B13%5D%5Bname%5D=maj&columns%5B13%5D%5Bsearchable%5D=true&columns%5B13%5D%5Borderable%5D=true&columns%5B13%5D%5Bsearch%5D%5Bvalue%5D=0-4&columns%5B13%5D%5Bsearch%5D%5Bregex%5D=false&columns%5B14%5D%5Bdata%5D=14&columns%5B14%5D%5Bname%5D=min&columns%5B14%5D%5Bsearchable%5D=true&columns%5B14%5D%5Borderable%5D=true&columns%5B14%5D%5Bsearch%5D%5Bvalue%5D=0-4&columns%5B14%5D%5Bsearch%5D%5Bregex%5D=false&columns%5B15%5D%5Bdata%5D=15&columns%5B15%5D%5Bname%5D=hyb&columns%5B15%5D%5Bsearchable%5D=true&columns%5B15%5D%5Borderable%5D=true&columns%5B15%5D%5Bsearch%5D%5Bvalue%5D=0-4&columns%5B15%5D%5Bsearch%5D%5Bregex%5D=false&columns%5B16%5D%5Bdata%5D=16&columns%5B16%5D%5Bname%5D=sub&columns%5B16%5D%5Bsearchable%5D=true&columns%5B16%5D%5Borderable%5D=true&columns%5B16%5D%5Bsearch%5D%5Bvalue%5D=0-4&columns%5B16%5D%5Bsearch%5D%5Bregex%5D=false&order%5B0%5D%5Bcolumn%5D=0&order%5B0%5D%5Bdir%5D=asc&start=0&length=18&search%5Bvalue%5D=&search%5Bregex%5D=false&_=1561063193443'
The result should be a tab-separated file. An example of the first 5 rows of data is shown below:
alignment dist ecfp4 daylight topodist mces tdn tup rdn rup ldn lup mut maj min hyb sub c1ccccc1 ZINC000000967532 0 1.0 1.0 0 6 0 0 0 0 0 0 0 0 0 0 0 Cc1ccccc1 ZINC000000967534 1 0.25 0.5 1 6 0 1 0 0 0 0 0 0 0 0 1 Clc1ccccc1 ZINC000000896527 1 0.25 0.46153846153846156 1 6 0 1 0 0 0 0 0 0 0 0 1 Nc1ccccc1 ZINC000017886255 1 0.25 0.46153846153846156 1 6 0 1 0 0 0 0 0 0 0 0 1 Oc1ccccc1 ZINC000005133329 1 0.25 0.46153846153846156 1 6 0 1 0 0 0 0 0 0 0 0 1
List of Publicly Available Maps
Find updated list of maps https://sw.docking.org/search/maps
The SmallWorld API provides the following additional entry points:
/search/view
Provides data in JSON format.
- Here again you only need to change the hlid
curl 'https://sw.docking.org//search/view/?hlid=4&draw=8&columns%5B0%5D%5Bdata%5D=0&columns%5B0%5D%5Bname%5D=alignment&columns%5B0%5D%5Bsearchable%5D=true&columns%5B0%5D%5Borderable%5D=false&columns%5B0%5D%5Bsearch%5D%5Bvalue%5D=&columns%5B0%5D%5Bsearch%5D%5Bregex%5D=false&columns%5B1%5D%5Bdata%5D=1&columns%5B1%5D%5Bname%5D=dist&columns%5B1%5D%5Bsearchable%5D=true&columns%5B1%5D%5Borderable%5D=true&columns%5B1%5D%5Bsearch%5D%5Bvalue%5D=0-10&columns%5B1%5D%5Bsearch%5D%5Bregex%5D=false&columns%5B2%5D%5Bdata%5D=2&columns%5B2%5D%5Bname%5D=ecfp4&columns%5B2%5D%5Bsearchable%5D=true&columns%5B2%5D%5Borderable%5D=true&columns%5B2%5D%5Bsearch%5D%5Bvalue%5D=&columns%5B2%5D%5Bsearch%5D%5Bregex%5D=false&columns%5B3%5D%5Bdata%5D=3&columns%5B3%5D%5Bname%5D=daylight&columns%5B3%5D%5Bsearchable%5D=true&columns%5B3%5D%5Borderable%5D=true&columns%5B3%5D%5Bsearch%5D%5Bvalue%5D=&columns%5B3%5D%5Bsearch%5D%5Bregex%5D=false&columns%5B4%5D%5Bdata%5D=4&columns%5B4%5D%5Bname%5D=topodist&columns%5B4%5D%5Bsearchable%5D=true&columns%5B4%5D%5Borderable%5D=true&columns%5B4%5D%5Bsearch%5D%5Bvalue%5D=0-4&columns%5B4%5D%5Bsearch%5D%5Bregex%5D=false&columns%5B5%5D%5Bdata%5D=5&columns%5B5%5D%5Bname%5D=mces&columns%5B5%5D%5Bsearchable%5D=true&columns%5B5%5D%5Borderable%5D=true&columns%5B5%5D%5Bsearch%5D%5Bvalue%5D=&columns%5B5%5D%5Bsearch%5D%5Bregex%5D=false&columns%5B6%5D%5Bdata%5D=6&columns%5B6%5D%5Bname%5D=tdn&columns%5B6%5D%5Bsearchable%5D=true&columns%5B6%5D%5Borderable%5D=true&columns%5B6%5D%5Bsearch%5D%5Bvalue%5D=0-4&columns%5B6%5D%5Bsearch%5D%5Bregex%5D=false&columns%5B7%5D%5Bdata%5D=7&columns%5B7%5D%5Bname%5D=tup&columns%5B7%5D%5Bsearchable%5D=true&columns%5B7%5D%5Borderable%5D=true&columns%5B7%5D%5Bsearch%5D%5Bvalue%5D=0-4&columns%5B7%5D%5Bsearch%5D%5Bregex%5D=false&columns%5B8%5D%5Bdata%5D=8&columns%5B8%5D%5Bname%5D=rdn&columns%5B8%5D%5Bsearchable%5D=true&columns%5B8%5D%5Borderable%5D=true&columns%5B8%5D%5Bsearch%5D%5Bvalue%5D=0-4&columns%5B8%5D%5Bsearch%5D%5Bregex%5D=false&columns%5B9%5D%5Bdata%5D=9&columns%5B9%5D%5Bname%5D=rup&columns%5B9%5D%5Bsearchable%5D=true&columns%5B9%5D%5Borderable%5D=true&columns%5B9%5D%5Bsearch%5D%5Bvalue%5D=0-4&columns%5B9%5D%5Bsearch%5D%5Bregex%5D=false&columns%5B10%5D%5Bdata%5D=10&columns%5B10%5D%5Bname%5D=ldn&columns%5B10%5D%5Bsearchable%5D=true&columns%5B10%5D%5Borderable%5D=true&columns%5B10%5D%5Bsearch%5D%5Bvalue%5D=0-4&columns%5B10%5D%5Bsearch%5D%5Bregex%5D=false&columns%5B11%5D%5Bdata%5D=11&columns%5B11%5D%5Bname%5D=lup&columns%5B11%5D%5Bsearchable%5D=true&columns%5B11%5D%5Borderable%5D=true&columns%5B11%5D%5Bsearch%5D%5Bvalue%5D=0-4&columns%5B11%5D%5Bsearch%5D%5Bregex%5D=false&columns%5B12%5D%5Bdata%5D=12&columns%5B12%5D%5Bname%5D=mut&columns%5B12%5D%5Bsearchable%5D=true&columns%5B12%5D%5Borderable%5D=true&columns%5B12%5D%5Bsearch%5D%5Bvalue%5D=&columns%5B12%5D%5Bsearch%5D%5Bregex%5D=false&columns%5B13%5D%5Bdata%5D=13&columns%5B13%5D%5Bname%5D=maj&columns%5B13%5D%5Bsearchable%5D=true&columns%5B13%5D%5Borderable%5D=true&columns%5B13%5D%5Bsearch%5D%5Bvalue%5D=0-4&columns%5B13%5D%5Bsearch%5D%5Bregex%5D=false&columns%5B14%5D%5Bdata%5D=14&columns%5B14%5D%5Bname%5D=min&columns%5B14%5D%5Bsearchable%5D=true&columns%5B14%5D%5Borderable%5D=true&columns%5B14%5D%5Bsearch%5D%5Bvalue%5D=0-4&columns%5B14%5D%5Bsearch%5D%5Bregex%5D=false&columns%5B15%5D%5Bdata%5D=15&columns%5B15%5D%5Bname%5D=hyb&columns%5B15%5D%5Bsearchable%5D=true&columns%5B15%5D%5Borderable%5D=true&columns%5B15%5D%5Bsearch%5D%5Bvalue%5D=0-4&columns%5B15%5D%5Bsearch%5D%5Bregex%5D=false&columns%5B16%5D%5Bdata%5D=16&columns%5B16%5D%5Bname%5D=sub&columns%5B16%5D%5Bsearchable%5D=true&columns%5B16%5D%5Borderable%5D=true&columns%5B16%5D%5Bsearch%5D%5Bvalue%5D=0-4&columns%5B16%5D%5Bsearch%5D%5Bregex%5D=false&order%5B0%5D%5Bcolumn%5D=0&order%5B0%5D%5Bdir%5D=asc&start=0&length=18&search%5Bvalue%5D=&search%5Bregex%5D=false&_=1561063193443'
/search/maps
Lists all available dataset mapfiles. The response is a JSON detailing the map name, id prefix, resolve url
Example Request:
curl https://sw.docking.org/search/maps
/search/config
Retrieves the public server configuration as JSON including the list of available score functions. The names of the scoring functions can be provided as a parameter to the /search/submit endpoint. Example Request:
curl https://sw.docking.org/search/config