Home>MolPort API>Documentation

Find Chemicals

Services

Suppliers

Sales contact

+1 (215) 9991090

+1 (215) 9991090

sales@molport.com


At MolPort, we welcome your thoughts, comments, questions and feedback. Our customer services department will be happy to help you Monday to Friday 7 a.m. to 4 p.m. GMT (2 a.m. - 10 a.m. EST).
Exceptions - closed on national holidays in Latvia (headquarters).

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.



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

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



3.5. Sample projects


How to run the CURL sample


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

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

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":1000,"Chemical Similarity Index":0.9}' https://api.molport.com/api/chemical-search/search



Back

Find Chemicals

Services

Database

About Us

Resources

Share Molport

Subscribe to newsletter

2021 MolPort, v4.52, release date 16-04-2021 23:00 (+0200). All rights reserved.
This website or its third-party tools use cookies, which are necessary to its functioning and require to achieve the purposes illustrated in the Cookie Policy. If you want to know more or withdraw your consent to all or some of the cookies, please refer to the Cookie Policy. By clicking on Agree and closing this banner, scrolling this page, clicking a link or continuing to browse otherwise, you agree to the use of cookies.

Agree