Explore the Molport API full technical 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.

If the source data contains special characters, these characters are escaped. List of escaped special characters can be seen below.

Special Character	Escaped Output
Quotation mark (")	\"
Backslash (\)	\\
Slash (/)	\/
Backspace	\b
Form feed	\f
New line	\n
Carriage return	\r
Horizontal tab	\t

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

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.3.0.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:

exact search;
exact fragment search;
similarity search;
perfect search;
substructure search;
superstructure search;

Request:

METHOD	POST
URL	api.molport.com/api/chemical-search/search Supported protocols: http, https
JSON	API Key - string; API key provided by Molport to institutional organizations; 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 (default) Set Id - int, compound set identifier with possible values: SET__ALL = 0 (default) SET__NATURAL_COMPOUNDS = 1 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 10000; default value is 10000; 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

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":10000,
   "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": 10000,
            "Similarity Index": 0.0
         }
      ],
      "Version": "v.3.0.1"
   }
}

3.3. Orders

3.3.1. List orders

Description: Return all orders for the specific client ordered by order date descending.

Request:

API VERSION	1.0.0
METHOD	GET
URL	api.molport.com/api/orders Supported protocols: http, https
HTTP HEADERS	MOLPORT-API-ID - string; predefined value Order-Tracking MOLPORT-API-KEY - string; API key provided by Molport individually for client If no valid header values provided, request will be rejected.

Response:

DATA TYPE

JSON, array of objects

JSON

200 (OK) - the request was successful

[
  {
    compounds_ordered - int; ordered compound count;
    compounds_cancelled - int; cancelled compound count;
    compounds_shipped - int; already shipped compound count;
    compounds_processing - int; compound count beeing processed;
    molport_order_number - string; Molport order number;
    order_date - date; order date;
    status_as_text - string; order status;
    key - string; order unique id;
  }, ...
]

401 (Unauthorized) - authentication failed or user doesn't have permissions for requested operation
403 (Forbidden) - access denied, header values not provided

3.3.2. Load order

Description: Return 1 specific order.

Request:

API VERSION	1.0.0
METHOD	GET
URL	api.molport.com/api/order/[id] Supported protocols: http, https
HTTP HEADERS	MOLPORT-API-ID - string; predefined value Order-Tracking MOLPORT-API-KEY - string; API key provided by Molport individually for client If no valid header values provided, request will be rejected.

Response:

DATA TYPE

JSON, array of objects

JSON

200 (OK) - the request was successful and orders were extracted

{
    compounds ordered - int; ordered compound count;
    compounds cancelled - int; cancelled compound count;
    compounds shipped - int; already shipped compound count;
    compounds processing - int; compound count beeing processed;
    molport order number - string; Molport order number;
    order date - date; order date;
    status as text - string; order status;
    key - string; order unique id;
    items:
    [
      {
        supplier name - string, supplier name;
        catalogue number - string, supplier catalogue number;
        molport catalogue number - string, Molport catalogue number;
        molport reference number - string, Molport reference number;
        quantity - int, quantity;
        quantity measure - string, quantity measure;
        status as text - string, status;
        invoice number - string, invoice number
        promised shipped out date - date, promised shipped out date (the value
        is frequently updated; in order to get the latest information, it needs to be requested regularly);
        shipped out date - date, shipped out date
      }, ...
    ]
}

401 (Unauthorized) - authentication failed or user doesn't have permissions for requested operation
403 (Forbidden) - access denied, header values not provided

3.4. Limitations

You can make up to 3 chemical search queries simultaneously. After exceeding this limit, an error announcement will appear that will limit your search traffic.

You can also make 3 active molecule catalog search queries to retrieve information from our database in parallel to chemical search queries. Similarly the same error announcement will appear when exceeding this limit.

Each users API account is limited to 10000 requests per month, meaning each user can submit up to 10000 requests each month. The remaining request count is refreshed at the start of each month. If you require more requests per month you can contact sales@molport.com to request an increased monthly cap.

3.5. Sample projects

How to run the CURL sample

Example below describes how to run the CURL sample. Please, perform the following steps:

Install CURL:
a: On Win machine install CURL or Cygwin.
b: On LINUX/Mac machine CURL is available out of the box.
Execute in command line API request with CURL.

curl --header "Content-Type: application/json" --request POST --data '{"API Key":"880d8343-8ui2-418c-9g7a-68b4e2e78c8b","Structure":"CC(C)(C)OC(=O)N1CCCCCC1C(O)=O","Search Type":"4","Maximum Search Time":60000,"Maximum Result Count":10000,"Chemical Similarity Index":0.9}' https://api.molport.com/api/chemical-search/search

How to run the JavaScript sample

Example below describes how to run the CURL sample. Please, perform the following steps:

Download the Molport archive MolPort-Molecule-v.3.0.zip with HTML file. Decompress the download archive.
Open HTML file in browser.
Enter username and authentication code provided by Molport.
Specify SMILES and chemical search type.
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/authentification code.

How to run the Java sample

Example below describes how to run the Molport Java API demo project on Microsoft Windows platform. With minor modifications, it can be run on NIX platforms (Linux, AIX, etc.) too. To use the jar and run the application, perform the following steps:

Download and install latest Oracle Java version. Remember, to download the correct bit version of install package. For example, if OS is 64-bit version, install 64-bit version of Java.
Download the Molport archive Molport-Molecule-v.3.0.zip with executable jar file and Java source.
Create test directory C:\molport-test.
Unarchive zip package, copy test-jar.jar and lib directory with jar's from bin directory of archive to test directory.
Change active directory to test directory - execute cd C:\molport-test in command prompt (Start -> run -> cmd).
Run test jar with username and password provided by Molport.

To execute chemical search:

java -jar test-jar.jar <username> <password> chemicalsearch <SMILES> <search type>

Sample for CC(C)(C)OC(=O)N1CCCCCC1C(O)=O exact fragment search:

java -jar test-jar.jar <username> <password> chemicalsearch CC(C)(C)OC(=O)N1CCCCCC1C(O)=O 6

To load information about molecule:

java -jar test-jar.jar <username> <password> loadmolecule <Molport molecule id>

Sample for molecule Molport-002-463-875:

java -jar test-jar.jar <username> <password> loadmolecule Molport-002-463-875

Build from Java source

The MolPort-Molecule-v.3.0.zip archive contains directory src with Java source files. Create a new empty command line project in your preferred Java IDE (Eclipse, Oracle JDeveloper, NetBeans, etc.) and add source files to the project.
The MolPort-Molecule-v.3.0.zip archive contains directory lib with dependant *.jar files from Apache HttpComponents project.
Build the Java project.
Run the main class Main.java and provide username, user password and Molport molecule ID as input arguments.
Check the output.
Implement the routines for data processing (deserialization for all returned data fields, data storing in database, file, etc.).
If necessary, deploy functionality as jar file using standard deployment descriptors provided by IDE or build jar with ANT.

Limitations

Please, contact Molport to aquire username and password/authentification code.

How to run the C# sample

Example below describes how to run the Molport C# API demo project on Microsoft Windows platform. To use the exe, perform the following steps:

Install Microsoft .Net 4.5 Framework if it is not already installed on machine.
Download the Molport archive Molport-Molecule-v.3.0.zip with executable exe file and C# project.
Create test directory C:\molport-test.
Unarchive zip package, copy MolPortAPIExample.exe from bin directory to test directory.
Change active directory to test directory - cd C:\molport-test in command prompt (Start -> run -> cmd).
Run MolPortAPIExample.exe with username and password provided by Molport.

To execute chemical search:

MolPortAPIExample.exe <username> <password> chemicalsearch <SMILES>

Sample for CC(C)(C)OC(=O)N1CCCCCC1C(O)=O exact fragment search:

MolPortAPIExample.exe <username> <password> chemicalsearch CC(C)(C)OC(=O)N1CCCCCC1C(O)=O

To load information about molecule:

MolPortAPIExample.exe <username> <password> moleculesearch <Molport molecule id>

Sample for molecule Molport-002-463-875:

MolPortAPIExample.exe <username> <password> moleculesearch Molport-002-463-875

Build from C# source

Unarchive the Molport-Molecule-v.3.0.zip archive.
Open the MolPortExample.csproj project file in Microsoft Visual Studio Community 2017.
Open the project properties and in section Debug fill field Command line arguments providing username, user password, action and search value (Molport molecule ID|SMILES) as input arguments.
Build and run the demo project.
Check the console output.

Limitations

Please, contact Molport to aquire username and password/authentification code.

How to run the Python sample

Example below describes how to run the Molport Python API demo sample on Microsoft Windows platform. To run te script, perform the following steps:

Download and install latest Python version (v.3.9.1 at the moment of writing this guide).
Open the Command Prompt - click on Windows Start Menu -> Run -> type in: cmd -> press Ok.
Execute the following command: py -m pip install requests. It will install an additional module required to run the script.
Create test directory C:\molport-test.
Download the Molport archive Molport-Molecule-v.3.0.Python.zip with py API test script file and unarchive zip package in test directory.
By using cd command, navigate to the directory C:\molport-test containing the script file.
Run the script with the following command: py python_example.py. The result will be printed in the console, and a .json file will be created in the script directory.

Limitations

Please, contact Molport to aquire username and password/authentification code.

Molport API Documentation

1. Introduction

2. Generic Structure of Request and Response

3. API Methods

3.1. Load molecule

3.2. Search molecules with chemical search

3.3. Orders

3.3.1. List orders

3.3.2. Load order

3.4. Limitations

3.5. Sample projects