User Tools

Site Tools


api

Differences

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

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision
Previous revision
Next revisionBoth sides next revision
api [2019/11/29 16:04] flackapi [2020/08/03 18:00] – [Substructure search] flack
Line 1: Line 1:
 API base url: https://mcule.com/api/v1/ API base url: https://mcule.com/api/v1/
  
-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.
  
 ====== Response status codes ====== ====== Response status codes ======
Line 90: Line 92:
 } }
 </code> </code>
 +
 +If you call this API endpoint as an authenticated user (=you provide a [[api#authentication|valid token]]) you might get additional private entries if you have permission to access them.
  
  
Line 231: Line 235:
  
 Authentication is currently a token based authentication. Authentication is currently a token based authentication.
-If you would like to access our protected API endpoints, please drop us an email at support@mcule.com and we can provide you with token.+If you would like to access our protected API endpoints, please drop us an email at support@mcule.com including a brief summary on why and how you would like to use the API. We'll review your request, and if accepted, we'll provide you with an access token which you can use to call the API as an authenticated user.
  
 Once you have a valid token you have to send it in the Authorization header: Once you have a valid token you have to send it in the Authorization header:
Line 383: Line 387:
     "results": [     "results": [
         {         {
-            "input_index": 1,  +            "input_index": 1
-            "mcule_id": "MCULE-9380369173",  +            "matching_level": 40, 
-            "smiles": "COC(C1SC(C=CC2SC(C3=NC=CC=C3)=NC=2)=NC=1)=O", +            "matching_level_display": "Atom graph"
 +            "mcule_id": "MCULE-9380369173", 
 +            "query": "COC(C1SC(C=CC2SC(C3=NC=CC=C3)=NC=2)=NC=1)=O", 
 +            "smiles": "COC(C1SC(C=CC2SC(C3=NC=CC=C3)=NC=2)=NC=1)=O",
             "url": "https://mcule.com/MCULE-9380369173/"             "url": "https://mcule.com/MCULE-9380369173/"
-        }, +        },
         {         {
-            "input_index": 2,  +            "input_index": 2
-            "mcule_id": "MCULE-4016901520",  +            "matching_level": 20, 
-            "smiles": "CC1=C(C(N2CC3C(CCC3N)C2)=O)SC(CC2=CC=CC=C2)=N1", +            "matching_level_display": "Sp3 configuration"
 +            "mcule_id": "MCULE-4016901520", 
 +            "query": "CC1=C(C(N2CC3C(CCC3N)C2)=O)SC(CC2=CC=CC=C2)=N1", 
 +            "smiles": "CC1=C(C(N2CC3C(CCC3N)C2)=O)SC(CC2=CC=CC=C2)=N1",
             "url": "https://mcule.com/MCULE-4016901520/"             "url": "https://mcule.com/MCULE-4016901520/"
-        }, +        },
         {         {
-            "input_index": 3,  +            "input_index": 3
-            "mcule_id": "MCULE-7428195288",  +            "matching_level": 40, 
-            "smiles": "C1([C@H](C(C)C)NC(CCCC[C@H]2CCSS2)=O)NC2=C(C=CC=C2)N=1",  +            "matching_level_display": "Atom graph"
-            "url": "https://mcule.com/MCULE-7428195288/" +            "mcule_id": "MCULE-1039596211", 
-        }, +            "query": "C1([C@H](C(C)C)NC(CCCCC2CCSS2)=O)NC2=C(C=CC=C2)N=1", 
 +            "smiles": "C1(C(C(C)C)NC(CCCCC2CCSS2)=O)NC2=C(C=CC=C2)N=1", 
 +            "url": "https://mcule.com/MCULE-1039596211/" 
 +        },
         {         {
-            "input_index": 5,  +            "input_index": 5
-            "mcule_id": "MCULE-1259420189",  +            "matching_level": 40, 
-            "smiles": "CCCCC1=CC=C(CC(N(CC2CCN(C)CC2)C)=O)C=C1", +            "matching_level_display": "Atom graph"
 +            "mcule_id": "MCULE-1259420189", 
 +            "query": "CCCCC1=CC=C(CC(N(CC2CCN(C)CC2)C)=O)C=C1", 
 +            "smiles": "CCCCC1=CC=C(CC(N(CC2CCN(C)CC2)C)=O)C=C1",
             "url": "https://mcule.com/MCULE-1259420189/"             "url": "https://mcule.com/MCULE-1259420189/"
         }         }
Line 409: Line 425:
 } }
 </code> </code>
 +
 +Please note that in case the queries are InChIKeys, **matching_level** and **matching_level_display** will always be **null** in the response. 
  
 ===== Multiple queries exact search with availability ===== ===== Multiple queries exact search with availability =====
Line 449: Line 467:
         {         {
             "availability": {             "availability": {
-                "availability_type": "in stock",  +                "availability_type": "in stock", 
-                "confirmed_amount": 242+                "confirmed_amount": 100,
                 "confirmed_amount_unit": "mg"                 "confirmed_amount_unit": "mg"
-            },  +            }, 
-            "input_index": 1,  +            "input_index": 1
-            "mcule_id": "MCULE-9380369173",  +            "matching_level": 40, 
-            "smiles": "COC(C1SC(C=CC2SC(C3=NC=CC=C3)=NC=2)=NC=1)=O", +            "matching_level_display": "Atom graph"
 +            "mcule_id": "MCULE-9380369173", 
 +            "query": "COC(C1SC(C=CC2SC(C3=NC=CC=C3)=NC=2)=NC=1)=O", 
 +            "smiles": "COC(C1SC(C=CC2SC(C3=NC=CC=C3)=NC=2)=NC=1)=O",
             "url": "https://mcule.com/MCULE-9380369173/"             "url": "https://mcule.com/MCULE-9380369173/"
-        }, +        },
         {         {
             "availability": {             "availability": {
-                "availability_type": "in stock",  +                "availability_type": "potentially purchasable", 
-                "confirmed_amount": null, +                "confirmed_amount": null,
                 "confirmed_amount_unit": "mg"                 "confirmed_amount_unit": "mg"
-            },  +            }, 
-            "input_index": 2,  +            "input_index": 2
-            "mcule_id": "MCULE-4016901520",  +            "matching_level": 20, 
-            "smiles": "CC1=C(C(N2CC3C(CCC3N)C2)=O)SC(CC2=CC=CC=C2)=N1", +            "matching_level_display": "Sp3 configuration"
 +            "mcule_id": "MCULE-4016901520", 
 +            "query": "CC1=C(C(N2CC3C(CCC3N)C2)=O)SC(CC2=CC=CC=C2)=N1", 
 +            "smiles": "CC1=C(C(N2CC3C(CCC3N)C2)=O)SC(CC2=CC=CC=C2)=N1",
             "url": "https://mcule.com/MCULE-4016901520/"             "url": "https://mcule.com/MCULE-4016901520/"
-        }, +        },
         {         {
             "availability": {             "availability": {
-                "availability_type": "in stock",  +                "availability_type": "in stock", 
-                "confirmed_amount": null+                "confirmed_amount": 50,
                 "confirmed_amount_unit": "mg"                 "confirmed_amount_unit": "mg"
-            },  +            }, 
-            "input_index": 3,  +            "input_index": 3
-            "mcule_id": "MCULE-7428195288",  +            "matching_level": 40, 
-            "smiles": "C1([C@H](C(C)C)NC(CCCC[C@H]2CCSS2)=O)NC2=C(C=CC=C2)N=1",  +            "matching_level_display": "Atom graph"
-            "url": "https://mcule.com/MCULE-7428195288/" +            "mcule_id": "MCULE-1039596211", 
-        }, +            "query": "C1([C@H](C(C)C)NC(CCCCC2CCSS2)=O)NC2=C(C=CC=C2)N=1", 
 +            "smiles": "C1(C(C(C)C)NC(CCCCC2CCSS2)=O)NC2=C(C=CC=C2)N=1", 
 +            "url": "https://mcule.com/MCULE-1039596211/" 
 +        },
         {         {
             "availability": {             "availability": {
-                "availability_type": "potentially purchasable",  +                "availability_type": "potentially purchasable", 
-                "confirmed_amount": null, +                "confirmed_amount": null,
                 "confirmed_amount_unit": "mg"                 "confirmed_amount_unit": "mg"
-            },  +            }, 
-            "input_index": 5,  +            "input_index": 5
-            "mcule_id": "MCULE-1259420189",  +            "matching_level": 40, 
-            "smiles": "CCCCC1=CC=C(CC(N(CC2CCN(C)CC2)C)=O)C=C1", +            "matching_level_display": "Atom graph"
 +            "mcule_id": "MCULE-1259420189", 
 +            "query": "CCCCC1=CC=C(CC(N(CC2CCN(C)CC2)C)=O)C=C1", 
 +            "smiles": "CCCCC1=CC=C(CC(N(CC2CCN(C)CC2)C)=O)C=C1",
             "url": "https://mcule.com/MCULE-1259420189/"             "url": "https://mcule.com/MCULE-1259420189/"
         }         }
     ]     ]
-+
 +</code> 
 + 
 +Please note that in case the queries are InChIKeys, **matching_level** and **matching_level_display** will always be **null** in the response.  
 + 
 + 
 +===== Similarity search ===== 
 +Similarity search currently accepts the following input identifiers: mcule ID, SMILES. 
 + 
 +== Endpoint: == 
 +<code>/search/sim/</code> 
 + 
 +== Example API request: == 
 +<code> 
 +echo '{"query": "MCULE-3601132784", "limit": 3, "threshold": 0.8}' | http https://mcule.com/api/v1/search/sim/ "Authorization: Token <your_token>" --print HBhb 
 +</code> 
 + 
 +or 
 + 
 +<code> 
 +echo '{"query": "CC1=C(C(CC2NC(=O)C3=C(SC(C4=CC=CC=C4)=C3)N=2)=O)C=CO1", "limit": 3, "threshold": 0.8}' | http https://mcule.com/api/v1/search/sim/ "Authorization: Token <your_token>" --print HBhb 
 +</code> 
 + 
 +== Request: == 
 +<code> 
 +POST /api/v1/search/sim/ HTTP/1.1 
 +Accept: application/json 
 +Accept-Encoding: gzip, deflate 
 +Authorization: Token <your_token> 
 +Content-Type: application/json 
 + 
 +
 +    "limit": 3, 
 +    "query": "MCULE-3601132784", 
 +    "threshold": 0.8 
 +
 +</code> 
 + 
 +== Response: == 
 +<code> 
 +HTTP/1.1 200 OK 
 +Allow: POST, OPTIONS 
 +Content-Encoding: gzip 
 +Content-Type: application/json 
 + 
 +
 +    "results":
 +        { 
 +            "mcule_id": "MCULE-3601132784", 
 +            "sim": 1.0, 
 +            "smiles": "CC1=C(C(CC2NC(=O)C3=C(SC(C4=CC=CC=C4)=C3)N=2)=O)C=CO1", 
 +            "url": "https://mcule.com/MCULE-3601132784/" 
 +        }, 
 +        { 
 +            "mcule_id": "MCULE-1000774360", 
 +            "sim": 0.8540706605222734, 
 +            "smiles": "O=C(C1OC=CC=1)CC1NC(=O)C2=C(SC(C3=CC=CC=C3)=C2)N=1", 
 +            "url": "https://mcule.com/MCULE-1000774360/" 
 +        }, 
 +        { 
 +            "mcule_id": "MCULE-9463088657", 
 +            "sim": 0.8529886914378029, 
 +            "smiles": "CC1SC2=C(C(NC(=N2)CC(C2=C(C)OC=C2)=O)=O)C=1", 
 +            "url": "https://mcule.com/MCULE-9463088657/" 
 +        } 
 +    ] 
 +
 +</code> 
 + 
 +The **threshold** field accepts values between 0.7 and 1.0, the default is 0.9. 
 + 
 +The **limit** field accepts values between 1 and 1000, the default is 100. 
 + 
 + 
 +===== Substructure search ===== 
 +Substructure search currently accepts the following input identifiers: mcule ID, SMILES. 
 + 
 +== Endpoint: == 
 +<code>/search/sss/</code> 
 + 
 +== Example API request: == 
 +<code> 
 +echo '{"query": "CC1=CC2=C(S1)N=CNC2=O", "limit": 5}' | http https://mcule.com/api/v1/search/sss/ "Authorization: Token <your_token>" --print HBhb 
 +</code> 
 + 
 +== Request: == 
 +<code> 
 +POST /api/v1/search/sss/ HTTP/1.1 
 +Accept: application/json 
 +Accept-Encoding: gzip, deflate 
 +Authorization: Token <your_token> 
 +Content-Type: application/json 
 + 
 +
 +    "limit": 5, 
 +    "query": "CC1=CC2=C(S1)N=CNC2=O" 
 +
 +</code> 
 + 
 +== Response: == 
 +<code> 
 +HTTP/1.1 200 OK 
 +Allow: POST, OPTIONS 
 +Content-Encoding: gzip 
 +Content-Type: application/json 
 + 
 +
 +    "results":
 +        { 
 +            "mcule_id": "MCULE-8112694353", 
 +            "smiles": "C12C(C)=C(SC=1N=CN(CC(NCCCC(=O)NC1CCCCC1)=O)C2=O)C", 
 +            "url": "https://mcule.com/MCULE-8112694353/" 
 +        }, 
 +        { 
 +            "mcule_id": "MCULE-8986577308", 
 +            "smiles": "C12SC3=C(CCCC3)C=1C(NC(SCC#C)=N2)=O", 
 +            "url": "https://mcule.com/MCULE-8986577308/" 
 +        }, 
 +        { 
 +            "mcule_id": "MCULE-4695228882", 
 +            "smiles": "C12SC3=C(CCCC3)C=1C(NC(SCCCC)=N2)=O", 
 +            "url": "https://mcule.com/MCULE-4695228882/" 
 +        }, 
 +        { 
 +            "mcule_id": "MCULE-1137030903", 
 +            "smiles": "N1(CC2C=NN(C)C=2)C(=O)C2C=C(SC=2N=C1S)CC", 
 +            "url": "https://mcule.com/MCULE-1137030903/" 
 +        }, 
 +        { 
 +            "mcule_id": "MCULE-1308684767", 
 +            "smiles": "C12SC3=C(CCCC3)C=1C(NC(SCC=C)=N2)=O", 
 +            "url": "https://mcule.com/MCULE-1308684767/" 
 +        } 
 +    ] 
 +}
 </code> </code>
  
 +The **limit** field accepts values between 1 and 1000, the default is 100.
  
  
api.txt · Last modified: 2023/06/03 07:19 by flack