How to use SmallWorld API: Difference between revisions

From DISI
Jump to navigation Jump to search
Line 171: Line 171:
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 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
The results are sorted in starting with the highest ECFP4
 
===Example Request===
*Here you only need to change the hlid!
*Here you only need to change the hlid!


Revision as of 22:21, 20 June 2019

Introduction

The Web Services API for SmallWorld Documentation is found in Section 8.3 of the SmallWorld version 4.0 manual starting from page 30 to 36. Copyright ©2012-2017 NextMove Software Limited. I copied the section here, and provided a list of publicly available databases for searching on sw.docking.org and some simple examples at the bottom.

8.3 Web Services API Important Entry Points

Unless stated otherwise all API entry points operate on HTTP GET/POST requests. A search on the server is first submitted (/search/submit), this returns a stream of events that report the hit list id (hlid). You can then use this hlid to fetch results either as JSON (/search/view) or TSV (/ search/export). An example Java client, SwHttpClient.java, shows how this works.

/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 'http://sw.docking.org//search/submit?smi=c1ccccc1&db=ZINC-Interesting-297K&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":5908,"elap":"0.0 s","numEdges":0,"numNodes":0,"numWaveFront":1,"numEdgesPerSec":"NaN"}
 data:{"status":"Ground Control to Major Tom","hlid":5908,"elap":"0.0 s","numEdges":0,"numNodes":0,"numWaveFront":0,"numEdgesPerSec":0.0}
 data:{"status":"MORE","hlid":5908,"elap":"0.0 s","numEdges":1,"numNodes":2,"numWaveFront":3,"numEdgesPerSec":47.783445425332395}
 data:{"status":"MORE","hlid":5908,"elap":"0.0 s","numEdges":7,"numNodes":8,"numWaveFront":14,"numEdgesPerSec":237.99311152737997}
 data:{"status":"MORE","hlid":5908,"elap":"0.1 s","numEdges":47,"numNodes":42,"numWaveFront":51,"numEdgesPerSec":583.5923096639136}
 data:{"status":"MORE","hlid":5908,"elap":"0.4 s","numEdges":363,"numNodes":216,"numWaveFront":221,"numEdgesPerSec":884.1124840482239}
 data:{"status":"Ground Control to Major Tom","hlid":5908,"elap":"0.5 s","numEdges":363,"numNodes":216,"numWaveFront":221,"numEdgesPerSec":700.4466134439543}
 data:{"status":"Ground Control to Major Tom","hlid":5908,"elap":"1.0 s","numEdges":441,"numNodes":253,"numWaveFront":224,"numEdgesPerSec":426.04845162109694}
 data:{"status":"Ground Control to Major Tom","hlid":5908,"elap":"1.6 s","numEdges":441,"numNodes":253,"numWaveFront":224,"numEdgesPerSec":284.05782226150757}
 data:{"status":"Ground Control to Major Tom","hlid":5908,"elap":"2.1 s","numEdges":458,"numNodes":263,"numWaveFront":278,"numEdgesPerSec":223.1371219908375}
 data:{"status":"END","hlid":5908,"elap":"2.2 s","numEdges":2417,"numNodes":981,"numWaveFront":885,"numEdgesPerSec":1104.50351038177}

Here the hlid for my request was 5908.

/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 'http://sw.docking.org//search/export/?hlid=5908&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'

List of Publicly Available Maps

  • ZINC-Interesting-297K
  • BB-Stock-1.5M
  • In-Stock-13.9M
  • ZINC-All-For-Sale-1.2B
  • ZINC-All-1.2B
  • BB-all-for-sale-18M
  • ZINC-On-Demand-1B
  • GDB13-977M
  • Wait-OK-1B
  • WuXi-58.6M

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 'http://sw.docking.org//search/view/?hlid=5908&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 'http://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 'http://sw.docking.org/search/config'
Retrieved from "http://wiki.docking.org/index.php?title=How_to_use_SmallWorld_API&oldid=11818"