How to use SmallWorld API

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 "https://sw.docking.org/search/maps"

/search/view

View the results of a search.

Access the results of a search either using the a hit-list id or by using the query parameters to start a new search automatically.

Parameter	Type	Description
id	integer	Hit List id
smi	array	Query SMILES/SMARTS strings
db	string	Database name
fmt	string	Format of results: tsv,csv
scores	string	Scoring function(s) to use
top	integer	Only collect this many (top) results, this option allows more resource efficient searches
async	boolean	Start new searches asynchronously or not (returns right away) or wait until timeout for search to run (default)
dist	string	Maximum Anonymous Distance
sdist	string	Maximum Scored Distance
tdn	string	Terminal Down Bounds
tup	string	Terminal Up Bounds
rdn	string	Ring Down Bounds
rup	string	Ring Up Bounds
ldn	string	Linker Down Bounds
lup	string	Linker Up Bounds
maj	string	Major Transmutation Bounds (Aligned Atom Scores only)
min	string	Minor Transmutation Bounds (Aligned Atom Scores only)
sub	string	Substitution Bounds (Aligned Atom Scores only)
hyb	string	Hybridisation Bounds (Aligned Atom Scores only)
ms	string	Interpret a single SMILES query with multiple components as a multi-source (ms) search.

/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