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
start	integer	Number of hits returned starting from this index
length	integer	Number of total hits returned
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	array	Query SMILES/SMARTS strings (Required)
db	string	Database name (Required)
top	integer	Only collect this many (top) results, this option allows more resource efficient searches
dist	string	Maxmium Anonymous Distance
sdist	string	Maxmium Scored Distance
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)
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)

Examples

/search/view

Basic Usage

1. Search of similar entries to benzene in ZINC-All-22Q2-1.6B

    curl "https://sw.docking.org/search/view?smi=c1ccccc1&db=ZINC-All-22Q2-1.6B"

2. Search of similar entries to pyridine in ZINC-All-22Q2-1.6B. Display in TSV. Show results from 0 to 50

    curl "https://sw.docking.org/search/view?smi=c1ccccc1&db=ZINC-All-22Q2-1.6B&fmt=tsv&start=0&length=50"

Advanced Usage

Multi-Start Search

1. Search of similar entries to either benzene or the chlorobenzene in ZINC-All-22Q2-1.6B. Display in TSV. Only show top 20 results.

    curl "https://sw.docking.org/search/view?smi=c1ccccc1&smi=Clc1ccccc1&db=ZINC-All-22Q2-1.6B&fmt=tsv&length=30&top=20"

2. Search of similar entries to either benzene or the chlorobenzene in ZINC-All-22Q2-1.6B. Tagging which molecule the similarity is closest to. Display in TSV. Display 30 results

    curl "https://sw.docking.org/search/view?smi=c1ccccc1%20benzene&smi=Clc1ccccc1%20chlorobenzene&db=ZINC-All-22Q2-1.6B&fmt=tsv&length=30"

Asynchronous Searching

1. Search of similar entries to benzene in ZINC-All-22Q2-1.6B. Show 3 results that are within distance 1~2. Use an asynchronous query.

    curl "https://sw.docking.org/search/view?smi=c1ccccc1&db=ZINC-All-22Q2-1.6B&start=0&length=2&dist=1-2&async=true" | jq

   • When running asynchronous searches it is useful to use the JSON output as this reports what the search is doing in the background
   • After calling once the server will return right away and you will see something like:

     {
       "draw": 0,
       "recordsTotal": 0,
       "recordsFiltered": 0,
       "status": {
         "dist": 0,
         "state": "RUNNING",
         "restarts": 0,
         "nodeHits": 0,
         "nodeVisit": 0,
         "edgeVisit": 0,
         "elapTime": 0,
         "runTime": 0,
         "wavefront": 0
       },
       "data": []
     }

   • The search will tell you when it has finished and be marked as DONE:

     {
       "draw": 0,
       "recordsTotal": 19195,
       "recordsFiltered": 19046,
       "status": {
         "dist": 2,
         "state": "DONE",
         "restarts": 6,
         "nodeHits": 35,
         "nodeVisit": 41,
         "edgeVisit": 46,
         "elapTime": 47685,
         "runTime": 2529,
         "wavefront": 0
       },
       "data": [
         [
           {
             "id": "ZINC000078108232",
             "qryMappedSmiles": "[CH:1]1=[CH:2][CH:3]=[CH:4][CH:5]=[CH:6]1",
             "hitMappedSmiles": "[CH2:1]=[CH:2]/[CH:3]=[CH:4]\\[CH:5]=[CH2:6]",
             "anonIdx": "B5R0.2",
             "mf": "C<sub>6</sub>H<sub>8</sub>",
             "mw": "80.128",
             "atomMap": [
               0,
               1,
               2,
               3,
               4,
               5
             ],
             "atomScore": [
               2,
               1,
               1,
               1,
               1,
               2
             ],
             "hitSmiles": "C=C\\C=C/C=C ZINC000078108232",
             "qrySmiles": "c1ccccc1"
           },
           0.0,
           0.07692307692307693,
           1,
           1
         ],
         [
           {
             "id": "ZINC000001592588",
             "qryMappedSmiles": "[CH:1]1=[CH:2][CH:3]=[CH:4][CH:5]=[CH:6]1",
             "hitMappedSmiles": "[CH2:1]=[CH:2]/[CH:3]=[CH:4]/[CH:5]=[CH2:6]",
             "anonIdx": "B5R0.2",
             "mf": "C<sub>6</sub>H<sub>8</sub>",
             "mw": "80.128",
             "atomMap": [
               0,
               1,
               2,
               3,
               4,
               5
             ],
             "atomScore": [
               2,
               1,
               1,
               1,
               1,
               2
             ],
             "hitSmiles": "C=C\\C=C\\C=C ZINC000001592588",
             "qrySmiles": "c1ccccc1"
           },
           0.0,
           0.07692307692307693,
           1,
           1
         ]
       ]
     }