Differences

This shows you the differences between two versions of the page.

--- ultimate-api [2020/04/11 11:13] – [Query types] flack
+++ ultimate-api [2020/07/20 14:09] – [Quote Request API] flack
@@ Line 6: / Line 6: @@
 You can find in the examples below the full URLs you have to use.
-Examples are demonstrated with [[https://github.com/jkbrzt/httpie|HTTPie]].
+Examples are demonstrated with [[https://httpie.org/|HTTPie]].
 Only the most important request/response headers are shown in the examples below.
@@ Line 28: / Line 28: @@
   * 100 searches / day
-For authenticated users:
+For authenticated users (access token required, see below):
   * 100 searches / minute
@@ Line 53: / Line 53: @@
 ===== Query types =====
-The supported query types are currently: SMILES, InChIKey, IUPAC name, CAS number, Std InChI, ZINC ID, CHEMBL ID.
+The supported query types are currently: SMILES, InChIKey, Molfile or SDF string (V2000), IUPAC name, CAS number, Std InChI, ZINC ID, CHEMBL ID.
 We recommend to send your queries in SMILES format.
@@ Line 60: / Line 60: @@
 InChIKey support is limited to the case where the query compound is part of the Ultimate database.
 Example **InChIKey** query: <code>IHHITLNORGKBTP-UHFFFAOYSA-N</code>
+Example **Molfile string** query:
+<code>
+\n  -INDIGO-04112011472D\n\n 30 33  0  0  0  0  0  0  0  0999 V2000\n  -11.0851    4.8000    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\n  -11.0851    3.2000    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\n  -12.4708    2.4000    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\n  -12.4708    0.8000    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\n  -11.0851    0.0000    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\n   -9.6995    0.8000    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\n   -9.6995    2.4000    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\n   -8.3138    3.2000    0.0000 N   0  0  0  0  0  0  0  0  0  0  0  0\n   -6.9282    2.4000    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\n   -6.9282    0.8000    0.0000 O   0  0  0  0  0  0  0  0  0  0  0  0\n   -5.5426    3.2000    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\n   -4.1569    2.4000    0.0000 N   0  0  0  0  0  0  0  0  0  0  0  0\n   -4.1569    0.8000    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\n   -2.7713    0.0000    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\n   -1.3856    0.8000    0.0000 N   0  0  0  0  0  0  0  0  0  0  0  0\n   -1.3856    2.4000    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\n   -2.7713    3.2000    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\n    0.0000    0.0000    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\n    1.3856    0.8000    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\n    2.7713    0.0000    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\n    4.1569    0.8000    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\n    4.1569    2.4000    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\n    2.7713    3.2000    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\n    1.3856    2.4000    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\n    0.0000   -1.6000    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\n   -1.3856   -2.4000    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\n   -1.3856   -4.0000    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\n    0.0000   -4.8000    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\n    1.3856   -4.0000    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\n    1.3856   -2.4000    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\n  1  2  1  0  0  0  0\n  2  3  1  0  0  0  0\n  3  4  2  0  0  0  0\n  4  5  1  0  0  0  0\n  5  6  2  0  0  0  0\n  6  7  1  0  0  0  0\n  7  2  2  0  0  0  0\n  7  8  1  0  0  0  0\n  8  9  1  0  0  0  0\n  9 10  2  0  0  0  0\n  9 11  1  0  0  0  0\n 11 12  1  0  0  0  0\n 12 13  1  0  0  0  0\n 13 14  1  0  0  0  0\n 14 15  1  0  0  0  0\n 15 16  1  0  0  0  0\n 16 17  1  0  0  0  0\n 17 12  1  0  0  0  0\n 15 18  1  0  0  0  0\n 18 19  1  0  0  0  0\n 19 20  1  0  0  0  0\n 20 21  2  0  0  0  0\n 21 22  1  0  0  0  0\n 22 23  2  0  0  0  0\n 23 24  1  0  0  0  0\n 24 19  2  0  0  0  0\n 18 25  1  0  0  0  0\n 25 26  1  0  0  0  0\n 26 27  2  0  0  0  0\n 27 28  1  0  0  0  0\n 28 29  2  0  0  0  0\n 29 30  1  0  0  0  0\n 30 25  2  0  0  0  0\nM  END\n</code>
 IUPAC name resolution don't always work.
 Example **IUPAC name** query: <code>1-(2-aminoethyl)-N-(2-methoxyethyl)-6-(methylsulfanyl)-1H-pyrazolo[3,4-d]pyrimidin-4-amine</code>
-Resolving CAS numbers happens via an external service and don't always work.
+Resolving CAS numbers happens via an external service and don't always work or might be unstable.
 Example **CAS number** query: <code>64-17-5</code>
 Example **Std InChI** query: <code>InChI=1S/C24H32N4O5/c1-18(15-26-11-13-32-14-12-26)22(29)28-21(17-25(2)24(28)31)23(30)33-20-9-6-10-27(16-20)19-7-4-3-5-8-19/h3-5,7-8,20-21H,1,6,9-17H2,2H3</code>
-Resolving ZINC IDs happens via [[http://zinc.docking.org]]. Example **ZINC ID** query: <code>ZINC3589203</code>
+Resolving ZINC IDs happens via [[http://zinc.docking.org]] and might be unstable. Example **ZINC ID** query: <code>ZINC3589203</code>
-Resolving CHEMBL IDs happens via [[https://www.ebi.ac.uk/chembl/]]. Example **CHEMBL ID** query: <code>CHEMBL2165209</code>
+Resolving CHEMBL IDs happens via [[https://www.ebi.ac.uk/chembl/]] and might be unstable. Example **CHEMBL ID** query: <code>CHEMBL2165209</code>
 ===== Exact search =====
@@ Line 150: / Line 154: @@
 You have to use the value **sim** in the **type** parameter.
 You can limit the number of hits with the **limit** parameter. In this example we fetched the 5 most similar hits.
 The maximum allowed number of **limit** is 1000.
@@ Line 311: / Line 316: @@
    * **amount**: the amount value in mg. Default: 1, Min: 1, Max: 100. The **amount** can be specified for some, or all items in the **compounds** list. If the amount is not specified for an item in the **compounds** list, the "global" amount value is used for that item.
    * **currency**: Valid values are "USD", "EUR", "GBP". The default is "USD".
-   * **individual**: If //true// you will get individual prices for the compounds. If //false// you get "collective" prices for the compounds which means you will get prices in the context when you intend to "order" the compounds together. These "collective" prices take into account possible price jumps or other factors that might result in lower prices. The default value is //false//.
+   * **individual**: If //true// you will get individual prices for the compounds. If //false// you will get "collective" prices for the compounds which means you will get prices in the context when you intend to "order" the compounds together. These "collective" prices take into account possible price jumps or other factors that might result in lower prices. The default value is //false//.
@@ Line 622: / Line 627: @@
 You can notice that you get lower prices but those prices are only valid in the context where you order the compounds together.
+====== Quote Request API ======
+== Endpoint: ==
+<code>/iquote-queries/</code>
+== Example API request: ==
+<code>
+echo '{"compounds": ["RAQLVHPPDXCQDS-UHFFFAOYSA-N", "QWPFQODIGUYSLE-UHFFFAOYSA-N"], "amount": 1, "customer_name": "John Doe", "delivery_country": "US"}' | http https://ultimateapp.mcule.com/api/v1/iquote-queries/ "Authorization: Token <your_token>" --print HBhb
+</code>
+Mandatory fields:
+  * **compounds**: you can specify this field in multiple ways:
+     * list of InChIKeys (which you get from search results for example). For example: <code>{"compounds": ["VKCCTPSYCYARFI-UHFFFAOYSA-N", "DVPXLZBGJCHMEO-UHFFFAOYSA-N"]}</code>
+     * list of InChIKey, amount pairs. This is useful if you want to request quote for different amounts. For example: <code>{"compounds": [{"inchi_key": "VKCCTPSYCYARFI-UHFFFAOYSA-N", "amount": 1}, {"inchi_key": "DVPXLZBGJCHMEO-UHFFFAOYSA-N", "amount": 5}]}</code>
+  * **customer_name**: The customer's full name. It is optional if the name of the user who is making the API request (defined by the token) is specified.
+  * **delivery_country**: ISO 3166-1 alpha-2 code of the delivery country.
+Optional fields:
+  * **customer_email**: The customer's email address. By default it will be filled with the email address associated with the user making the API request (defined by the token).
+  * **currency**: Valid values are "USD", "EUR", "GBP". The default is "USD".
+  * **scheme**: If you have access to predefined quote request schemes, you can specify here which one you want to use. A quote query scheme is essentially a template that contains predefined quote query parameters, or even include private parameters that affect quote generation in various ways (e.g.: discounts, predefined custom prices). These parameters can be customized for your use case. The scheme might already contain mandatory fields like delivery_country. In this case you don't have to specify them again, they will be applied from the scheme. Any explicitly specified public parameter during the request will override the one that comes from the specified scheme.
+== Example request: ===
+<code>
+POST /api/v1/iquote-queries/ HTTP/1.1
+Accept: application/json, */*
+Accept-Encoding: gzip, deflate
+Authorization: Token <your_token>
+Content-Type: application/json
+{
+    "amount": 1,
+    "customer_name": "John Doe",
+    "delivery_country": "US",
+    "compounds": [
+        "RAQLVHPPDXCQDS-UHFFFAOYSA-N",
+        "QWPFQODIGUYSLE-UHFFFAOYSA-N"
+    ]
+}
+</code>
+== Example response: ===
+<code>
+HTTP/1.1 201 CREATED
+Allow: GET, POST, HEAD, OPTIONS
+Content-Type: application/json
+{
+    "amount": 1,
+    "api_url": "https://ultimateapp.mcule.com/api/v1/iquote-queries/9/",
+    "created_at": "2020-07-20T14:01:30.412763Z",
+    "currency": "USD",
+    "customer_email": "foo@bar.com",
+    "customer_name": "John Doe",
+    "delivery_country": {
+        "code": "US",
+        "name": "United States of America"
+    },
+    "delivery_format": 0,
+    "delivery_format_display": "Dry powder/film in supplier vial",
+    "ended_at": null,
+    "extra_amount": null,
+    "id": 9,
+    "notes": "",
+    "purity": null,
+    "scheme": 1,
+    "started_at": null,
+    "state": 10,
+    "state_display": "Pending",
+    "target_cc": null,
+    "target_volume": null,
+    "user": 2
+}
+</code>