MolPort API Documentation


The current, latest version of the MolPort API is v3.0. To prevent broken experiences for people, we strongly recommend to upgrade your application to the latest API version. Please, visit MolPort API History of Changes for the latest changes in API interfaces and/or data structures.



1. Introduction

MolPort API is implemented as REST interfaces. REST stands for Representational State Transfer. It relies on a stateless, client-server, cacheable communications. JSON (JavaScript Object Notation) is used as a lightweight data-interchange format.



2. Generic Structure of Request and Response


MolPort JSON request generic form is specific for API interface. Please, check the API Documentation to see the data structures that are used.

MolPort JSON response generic form:

{
  "Result": {
    "Status": 1|2,
    "Message": 
  },
  "Data": {
    "Version": ,
    … [Data Object] …
  }
}

where:
Status – int; possible values:
      1 – operation was successful,
      2 – operation was not successful;
Message – string; short informative, human readable message;
Version – string; version number of returned MolPort JSON data objects;
Data Object – json; JSON representation of returned data objects.



3. API Methods


3.1. Load molecule


Description: Method to load information about molecule from database if MolPort compound ID is known.

Request:

METHOD GET
URL

api.molport.com/api/molecule/load?molecule={MolPort molecule id}|{molecule id}&username={username}&authenticationcode={authentication code}

Supported protocols: http, https


Response:

DATA TYPE JSON
JSON

Id – int; molecule identifier in MolPort database;
MolPort Id – string, formatted molecule identifier in MolPort database;
SMILES – string; SMILES of molecule;
IUPAC – string; IUPAC of molecule;
Formula – string; molecular molecule;
Molecular Weight – string; molecular weight;
Status – string; status of availability;
Type – string; type of availability;
Largest Stock – string; maximum stock available in shop;
Largest Stock Measure – string; measure;
Largest Stock Measure Id – string; MolPort measure Id;
Synonyms – array of molecule names;
Catalogues – array of :
      Screening Block Suppliers – array of suppliers;
      Building Block Suppliers – array of suppliers;
      Virtual Suppliers – array of suppliers.

Method will return a Supplier objects with data structure:
Supplier Name – string; supplier name;
Supplier Id – int; supplier Id;
Minimum Order – double; minimum order for supplier;
Currency – string; currency ISO code;
Currency Id – int; MolPort currency identifier;
Catalogues – array of supplier catalogues.

Method will return a Catalogue objects with data structure:
Catalog Id – int; catalog Id in MolPort database;
Catalog Number – string; supplier catalog number;
Stock – double; amount in stock;
Stock Measure – string; amount measure;
Stock Measure Id – int; amount measure Id in MolPort database;
Last Update Date – string; last catalog update date in MolPort database;
Available Packings – array of packings.

Method will return a Packing objects with data structure:
Amount – string; amount;
Measure – string; amount measure;
Measure Id – int; amount measure Id in MolPort database;
Price – double; price;
Currency – string; currency;
Currency Id – int; currency Id in MolPort database;
Delivery Days – int; days in which supplier sends out requested molecules if payment was made.

Method will return a Synonym objects with data structure:
Value – string; name/MDL number of molecule.


Example:

URL

api.molport.com/api/molecule/load?molecule=2325020&username=john.spade&authenticationcode=fasdga34a3
or
api.molport.com/api/molecule/load?molecule=MolPort-002-325-020&username=john.spade&authenticationcode=fasdga34a3

Supported protocols: http, https

REQUEST

MolPort compound ID 2325020 or MolPort-002-325-020 in URL

RESPONSE
{
  "Result": {
    "Status": 1,
    "Message": "Molecule found!"
  },
  "Data": {
    "Molecule": {
      "Id": 2325020,
      "MolPort Id": "MolPort-002-325-020",
      "SMILES": "CCOC(O)c1[nH]c2ccc(C)cc2c1NC(O)CC",
      "IUPAC": "ethyl 5-methyl-3-propanamido-1H-indole-2-carboxylate",
      "Formula": "C15H18N2O3",
      "Molecular Weight": 274.32,
      "Status": "shop",
      "Type": "stock",
      "Largest Stock": "124",
      "Largest Stock Measure": "mg",
      "Largest Stock Measure Id": 234,
      "Catalogues": {
        "Screening Block Suppliers": [
          {
            "Supplier Name": "Specs",
            "Supplier Id": 2070,
            "Minimum Order": 200,
            "Currency": "USD",
            "Currency Id": 2,
            "Catalogues": [
              {
                "Catalog Id": 84777984,
                "Catalog Number": "AG-690/10530016",
                "Stock": 2,
                "Stock Measure": "mg",
                "Stock Measure Id": 234,
                "Last Update Date": "today",
                "Available Packings": [
                  {
                    "Amount": 2,
                    "Measure": "mg",
                    "Measure Id": 234,
                    "Price": 32.20,
                    "Currency": "USD",
                    "Currency Id": 2,
                    "Delivery Days": 7
                  }
                ]
              }
            ],
            "Shipment Costs": [
              {
                "Price": 50,
                "Currency": "USD",
                "Currency Id": 2,
                "Location Type": "REGION",
                "Location": "EUROPE",
                "Location Id": 1,
                "Shipment Type": "Basic Shipping",
                "Shipment Type Id": 3
              },
              {
                "Price": 50,
                "Currency": "USD",
                "Currency Id": 2,
                "Location Type": "REGION",
                "Location": "USA",
                "Location Id": 2,
                "Shipment Type": "Basic Shipping",
                "Shipment Type Id": 3
              },
              {
                "Price": 50,
                "Currency": "USD",
                "Currency Id": 2,
                "Location Type": "REGION",
                "Location": "CANADA AND MEXICO",
                "Location Id": 3,
                "Shipment Type": "Basic Shipping",
                "Shipment Type Id": 3
              },
              {
                "Price": 50,
                "Currency": "USD",
                "Currency Id": 2,
                "Location Type": "REGION",
                "Location": "OTHER LOCATIONS",
                "Location Id": 4,
                "Shipment Type": "Basic Shipping",
                "Shipment Type Id": 3
              }
            ]
          },
        ],
      },
      "Synonyms": [
        "ethyl",
        "ethyl 5-methyl-3-(propanoylamino)-1H-indole-2-carboxylate"
      ],
    },
    "Version": "v.1.1",
  }
}


3.2. Search molecules with chemical search


Description: Method to search molecules with chemical search if SMILES is known.

Currently supported chemical search types are:
      1) exact search;
      2) exact fragment search;
      3) similarity search;
      4) perfect search;
      5) substructure search;
      6) superstructure search;


Request:

METHOD POST
URL

api.molport.com/api/chemical-search/search

Supported protocols: http, https

JSON

User Name – string; username provided by MolPort;
Authentication Code – string; password provided by MolPort;
Structure – string; SMILES of molecule;
Search Type – int, chemical search type with possible values:
      CHEMICAL_SEARCH_TYPE__SUBSTRUCTURE = 1
      CHEMICAL_SEARCH_TYPE__SUPERSTRUCTURE = 2
      CHEMICAL_SEARCH_TYPE__EXACT = 3
      CHEMICAL_SEARCH_TYPE__SIMILARITY = 4
      CHEMICAL_SEARCH_TYPE__PERFECT = 5
      CHEMICAL_SEARCH_TYPE__EXACT_FRAGMENT = 6
Maximum Search Time – int; time in miliseconds - maximum search time to be spent on chemical search;
Maximum Result Count – int; maximum result count which must be returned as result; currently maximum allowed value is 1000; default value is 1000;
Chemical Similarity Index – double; if similarity search is made, it is possible to provide similarity index in range 0 – 1; default value is 0.9.


Response:

DATA TYPE JSON
JSON
{
  "Id": [MolPort molecule id],
  "MolPort Id": [formatted MolPort molecule id],
  "SMILES": [SMILES],
  "Similarity Index": [Similarity index]
}

where:

Id – int; molecule identifier in MolPort database;
MolPort Id – string, formatted molecule identifier in MolPort database;
SMILES – string; SMILES of molecule;
Canonical SMILES – string; canonical SMILES of molecule;
Verified Amount – int; verified max stock amount in milligrams;
Unverified Amount – int; unverified max stock amount in milligrams;
Similarity Index – double; if similarity search was made, will contain similarity index to initially searched molecule.


Example:

URL

api.molport.com/api/chemical-search/search

Supported protocols: http, https

REQUEST
{
  "User Name":"john.spade",
  "Authentication Code":"fasdga34a3",
  "Structure":"CC(C)(C)OC(=O)N1CCCCCC1C(O)=O",
  "Search Type":4,
  "Maximum Search Time":60000,
  "Maximum Result Count":1000,
  "Chemical Similarity Index":0.9
}
RESPONSE
{
  "Result": {
    "Status": 2,
    "Message": "Size: 2"
  },
  "Data": {
    "Molecules": [
      {
        "Id": 28065133,
        "MolPort Id": "MolPort-028-065-133",
        "SMILES": "CC(NC(O)COc1ccc(cc1)C(C)O)c1cccs1",
        "Canonical SMILES": "CC(=O)C1=CC=C(C=C1)OCC(=O)C2=CN(CCC#N)C3=CC=CC=C23",
        "Verified Amount": 0,
        "Unverified Amount": 1000,
        "Similarity Index": 0.0
      }
    ],
    "Version": "v.1.1"
  }
}


3.3. Sample projects


How to run the JavaScript sample


Example below describes how to run the MolPort JavaScript API demo project. Please, perform the following steps:

1. Download the MolPort archive MolPort-Molecule-v.3.0.zip with HTML file. Decompress the download archive.
2. Open HTML file in browser.
3. Enter username and authentication code provided by MolPort.
4. Specify SMILES and chemical search type.
5. Execute chemical search.




Source


Provided example uses AJAX (JSONP) to overcome cross-domain limitations. jQuery library is used to execute AJAX requests. Current example can be used reused without any limitations.




Limitations


Please, contact MolPort to aquire username and password/athentification code.



2017 MolPort, v2.24, release date 09-10-2017 13:00 (+0200). All rights reserved.