ultimate-api
Differences
This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revisionNext revision | Previous revisionNext revisionBoth sides next revision | ||
ultimate-api [2020/04/11 11:11] – [Query types] flack | ultimate-api [2020/07/21 10:26] – flack | ||
---|---|---|---|
Line 6: | Line 6: | ||
You can find in the examples below the full URLs you have to use. | You can find in the examples below the full URLs you have to use. | ||
- | Examples are demonstrated with [[https://github.com/jkbrzt/ | + | Examples are demonstrated with [[https://httpie.org/|HTTPie]]. |
Only the most important request/ | Only the most important request/ | ||
Line 28: | Line 28: | ||
* 100 searches / day | * 100 searches / day | ||
- | For authenticated users: | + | For authenticated users (access token required, see below): |
* 100 searches / minute | * 100 searches / minute | ||
Line 53: | Line 53: | ||
===== Query types ===== | ===== Query types ===== | ||
- | The supported query types are currently: SMILES, InChIKey, IUPAC name, CAS number, Std InChI, ZINC ID. | + | The supported query types are currently: SMILES, InChIKey, Molfile or SDF string (V2000), IUPAC name, CAS number, Std InChI, ZINC ID, CHEMBL |
We recommend to send your queries in SMILES format. | 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. | InChIKey support is limited to the case where the query compound is part of the Ultimate database. | ||
Example **InChIKey** query: < | Example **InChIKey** query: < | ||
+ | |||
+ | Example **Molfile string** query: | ||
+ | < | ||
+ | \n -INDIGO-04112011472D\n\n 30 33 0 0 0 0 0 0 0 0999 V2000\n | ||
IUPAC name resolution don't always work. | IUPAC name resolution don't always work. | ||
Example **IUPAC name** query: < | Example **IUPAC name** query: < | ||
- | 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: < | Example **CAS number** query: < | ||
Example **Std InChI** query: < | Example **Std InChI** query: < | ||
- | Resolving ZINC IDs happens via [[http:// | + | Resolving ZINC IDs happens via [[http:// |
- | Resolving CHEMBL IDs happens via [[https:// | + | Resolving CHEMBL IDs happens via [[https:// |
===== Exact search ===== | ===== Exact search ===== | ||
Line 150: | Line 154: | ||
You have to use the value **sim** in the **type** parameter. | 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. | 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. | 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 " | * **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 " | ||
* **currency**: | * **currency**: | ||
- | * **individual**: | + | * **individual**: |
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. | 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: == | ||
+ | < | ||
+ | |||
+ | == Example API request: == | ||
+ | < | ||
+ | echo ' | ||
+ | </ | ||
+ | |||
+ | Mandatory fields: | ||
+ | * **compounds**: | ||
+ | * list of InChIKeys (which you get from search results for example). For example: < | ||
+ | * list of InChIKey, amount pairs. This is useful if you want to request quote for different amounts. For example: < | ||
+ | * **customer_name**: | ||
+ | * **delivery_country**: | ||
+ | |||
+ | |||
+ | Optional fields: | ||
+ | * **customer_email**: | ||
+ | * **currency**: | ||
+ | * **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: === | ||
+ | < | ||
+ | POST / | ||
+ | Accept: application/ | ||
+ | Accept-Encoding: | ||
+ | Authorization: | ||
+ | Content-Type: | ||
+ | |||
+ | { | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | ] | ||
+ | } | ||
+ | </ | ||
+ | |||
+ | == Example response: === | ||
+ | < | ||
+ | HTTP/1.1 201 CREATED | ||
+ | Allow: GET, POST, HEAD, OPTIONS | ||
+ | Content-Type: | ||
+ | |||
+ | { | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | }, | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | } | ||
+ | </ | ||
+ | |||
+ | |||
+ | ====== Quote Request Status API ====== | ||
+ | |||
+ | Since processing a quote request and generating suitable quotes can take some time it is an asynchronous process. You can query the status of a quote request by calling the detail API endpoint of the quote request. It is returned in the **api_url** field when you create the quote request. You can also use the **id** field to construct the url of the API call. You can check the **state** field of the response whether the async quote request processing is finished. | ||
+ | |||
+ | States: | ||
+ | * **10 / Pending**: The quote query is queued but the processing has not started yet. | ||
+ | * **20 / Running**: The processing of the quote query is in progress. | ||
+ | * **30 / Done**: The processing of the quote query is finished. For one quote request query we might generate multiple quotes or it is also possible that we could not generate any quotes for a particular quote request. If there are quotes they will appear in the **quotes** field that contains a list of the generated quotes and some basic info about them. You can get detailed data of a particular quote by calling the endpoint specified in the **api_url** field. | ||
+ | * **40 / Error**: An error happened during the processing of the quote query. | ||
+ | |||
+ | Following the above example where the ID of the quote request is //9// we query the status of the quote request: | ||
+ | < | ||
+ | http https:// | ||
+ | </ | ||
+ | |||
+ | == Example request: === | ||
+ | |||
+ | < | ||
+ | GET / | ||
+ | Accept: */* | ||
+ | Accept-Encoding: | ||
+ | Authorization: | ||
+ | </ | ||
+ | |||
+ | == Example response: === | ||
+ | < | ||
+ | HTTP/1.1 200 OK | ||
+ | Allow: GET, HEAD, OPTIONS | ||
+ | Connection: keep-alive | ||
+ | Content-Encoding: | ||
+ | Content-Type: | ||
+ | |||
+ | { | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | }, | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | { | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | } | ||
+ | ], | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | }</ | ||
+ | |||
+ | Check for the **quotes** field. If it is there and contains some items in the list, we could generate some quotes for your quote query. As you can see from the above result, we could generate 1 quote for the quote query. A "Best price" quote. | ||
+ | |||
+ | |||
+ | ====== Quote API ====== | ||
+ | |||
+ | In order to get the detailed data of an individual quote, you can call the detail API endpoint of a quote, for example for the quote with ID //9//: | ||
+ | |||
+ | < | ||
+ | http https:// | ||
+ | </ | ||
+ | |||
+ | == Example request: === | ||
+ | < | ||
+ | GET / | ||
+ | Accept: */* | ||
+ | Accept-Encoding: | ||
+ | Authorization: | ||
+ | </ | ||
+ | |||
+ | == Example response: === | ||
+ | < | ||
+ | HTTP/1.1 200 OK | ||
+ | Allow: GET, HEAD, OPTIONS | ||
+ | Content-Encoding: | ||
+ | Content-Type: | ||
+ | |||
+ | { | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | { | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | }, | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | }, | ||
+ | { | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | }, | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | } | ||
+ | ], | ||
+ | " | ||
+ | " | ||
+ | { | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | }, | ||
+ | { | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | }, | ||
+ | { | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | }, | ||
+ | { | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | }, | ||
+ | { | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | } | ||
+ | ], | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | }, | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | }, | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | } | ||
+ | </ | ||
+ | |||
+ | == Fields: === | ||
+ | * **additional_document_notes**: | ||
+ | * **avg_product_price**: | ||
+ | * **avg_product_price_currency**: | ||
+ | * **coverage_percent**: | ||
+ | * **created_at**: | ||
+ | * **id**: The ID of the Instant Quote. | ||
+ | * **items**: list of product level data | ||
+ | * **amount**: Quoted amount (mg) | ||
+ | * **compound**: | ||
+ | * **product_price**: | ||
+ | * **product_price_currency**: | ||
+ | * **purity_percent**: | ||
+ | * **payment_due_days**: | ||
+ | * **price_items**: | ||
+ | * **product_discount_price**: | ||
+ | * **product_discount_price_currency**: | ||
+ | * **products_price**: | ||
+ | * **products_price_currency**: | ||
+ | * **query**: The quote query fields | ||
+ | * **reference_id_full**: | ||
+ | * **reformatting_price**: | ||
+ | * **reformatting_price_currency**: | ||
+ | * **selection_criteria**: | ||
+ | * **selection_criteria_display**: | ||
+ | * **shipping_price**: | ||
+ | * **shipping_price_currency**: | ||
+ | * **state**: State code of the quote. | ||
+ | * **state_display**: | ||
+ | * **total_discount_price**: | ||
+ | * **total_discount_price_currency**: | ||
+ | * **total_price**: | ||
+ | * **total_price_currency**: | ||
+ | * **valid_until**: | ||
+ | | ||
+ | ==== Download quote as PDF ==== | ||
+ | |||
+ | You can download a quote as a PDF file. Please note that the PDF file generation can take some time, the more item it contains the more time it will take to generate the file. | ||
+ | |||
+ | The HTTP response contains a // | ||
+ | |||
+ | < | ||
+ | http https:// | ||
+ | </ | ||
+ | |||
+ | ==== Download quote as Excel (.xlsx) file ==== | ||
+ | |||
+ | You can download a quote as an Excel file. Please note that the file generation can take some time, the more item it contains the more time it will take to generate the file. | ||
+ | |||
+ | The HTTP response contains a // | ||
+ | |||
+ | < | ||
+ | http https:// | ||
+ | </ | ||
+ | |||
+ | |||
+ | |||
+ |
ultimate-api.txt · Last modified: 2021/05/25 14:27 by flack