Developer's guide

    Authenticate with API key

    The Chemaxon Calculators and Predictors service is secured from unauthorized use by allowing only those API calls that provide proper authentication credentials. These credentials are in the form of an API key - a unique alphanumeric string associated to your AWS account.

    Getting the API key

    Once you subscribe to the Calculators and Predictors service on AWS Marketplace, you will be redirected to our welcome page where you can redeem your API key.

    {primary} Save the key and store it in a safe place. This is the only time we will show you the API key.

    • Once you close or refresh the window, you won't be able to recover the API key.
    • You will be charged for every API call that uses this key. Make sure you are the only one who has access to it.
    • Your API key will be activated once AWS fully processes your subscription. This typically takes a few seconds, but in rare cases it can take up to 30 minutes.

    Using the API key

    To gain access to our services, you must add the x-api-key header to all of your requests. The value of the header can only be the API key and nothing else:

    x-api-key: <YOUR_API_KEY>

    For detailed examples check the Code examples section.

    Revoking the API key

    To revoke your API key, you have to unsubscribe from our services on the AWS Marketplace product page. This action triggers mechanisms in the background that revoke your API key immediately.

    Re-generate the API key

    We don't provide this functionality as is, but you can unsubscribe from using Chemaxon Calculators and Predictors on AWS Marketplace product page and subscribe again. This has the effect of revoking your current API key and getting a new one.

    Subscribing and unsubscribing to the service is free of charge. We only charge you for the API calls you make.

    Check API key validity

    You can check any time if your API key is still valid at marketplace.calculators.cxn.io. In case of a valid API key we provide additional information, e.g. the pricing plan you chose. For more information, see Pricing.

    API Limitations

    Maximum execution time

    Each request is allowed to run for a maximum of 25 seconds. After that time period your request calls a timeout and returns with HTTP status code 504 Gateway Timeout.

    Rate limit

    A rate limit is the number of API calls a user can make within a given time period. Our system limits API calls to 50 request/sec. Please note that this is not hard limit but rather applied on a best-effort basis. In some cases you can exceed the rate that you set.

    Maximum number of structures within a batch call

    Calculators and Predictors on AWS Marketplace provides an API (/rest-v1/calculator/batch/calculate) that allows calculations for multiple structures within a single call. The maximum number of structures is limited to 25 structures.

    API documentation

    A temporary API documentation can be found at this swagger page.

    AWS PrivateLink

    What is AWS PrivateLink?

    AWS PrivateLink is a highly available, scalable technology that enables you to privately connect your VPC to services as if they were in your VPC. Therefore, you control the specific API endpoints, sites and services that are reachable from your VPC.

    Available AWS regions and their endpoint service names for PrivateLink connection:

    • eu-west-1: com.amazonaws.vpce.eu-west-1.vpce-svc-0de31eeb3a6603741
    • us-east-2: com.amazonaws.vpce.us-east-2.vpce-svc-0227bb48a9c19e263

    How to connect to Chemaxon Calculators and Predictors using the PrivateLink option?

    AWS Console:

    AWS CLI:

    aws ec2 create-vpc-endpoint \
       --vpc-id <vpc-id> \
       --subnet-ids <subnet-id> \
       --service-name com.amazonaws.vpce.eu-west-1.vpce-svc-0de31eeb3a6603741 \
       --private-dns-enabled

    Is it possible to use the service via PrivateLink from a VPC that is located outside of the available regions (e.g. us-west-1)?

    Yes, it is possible with the following steps:

    • Create a VPC in any supported region, e.g. us-east-2.
    • Connect to our service via PrivateLink from this VPC.
    • Create an inter-region VPC peering connection between your VPCs (us-east-2 vs us-west-1).

    Code examples

    The following section provides code examples in different languages on how to use a basic calculator (Elemental Analysis) by authenticating the request using the API key.

    curl

    curl -X 'POST' \
      'https://api.calculators.cxn.io/rest-v1/calculator/calculate/elemental-analysis' \
      -H 'accept: application/json' \
      -H 'Content-Type: application/json' \
      -H 'x-api-key: YOUR_API_KEY' \
      -d '{
      "structure": "NC(CC1=CC=CC=C1)C(O)=O"
    }'

    Javascript

    const url = 'https://api.calculators.cxn.io/rest-v1/calculator/calculate/elemental-analysis';
    const payload = {
      structure: 'NC(CC1=CC=CC=C1)C(O)=O'
    };
    
    const response = await fetch(url, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': 'YOUR_API_KEY',
      },
      body: JSON.stringify(payload)
    });

    Python

    import requests
    
    url = 'https://api.calculators.cxn.io/rest-v1/calculator/calculate/elemental-analysis'
    payload = { 'structure': 'NC(CC1=CC=CC=C1)C(O)=O' }
    my_headers = {
      'x-api-key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    }
    
    response = requests.post(url, json=payload, headers=my_headers)

    Java

    import java.net.URI;
    import java.net.http.HttpClient;
    import java.net.http.HttpRequest;
    import java.net.http.HttpRequest.BodyPublishers;
    import java.net.http.HttpResponse;
    import java.net.http.HttpResponse.BodyHandlers;
    import java.time.Duration;
    
    import com.google.gson.Gson;
    
    public class App {
      public static void main(String[] args) {
        // This code requires Java 11 or newer
        var request = HttpRequest.newBuilder()
          .uri(URI.create("https://api.calculators.cxn.io/rest-v1/calculator/calculate/elemental-analysis"))
          .header("x-api-key", "YOUR_API_KEY")
          .header("Content-Type", "application/json")
          .POST(BodyPublishers.ofString("{ \"structure\": \"NC(CC1=CC=CC=C1)C(O)=O\" }"))
          .timeout(Duration.ofSeconds(5))
          .build();
    
        var responseStr = HttpClient.newHttpClient()
          .sendAsync(request, BodyHandlers.ofString())
          .thenApply(HttpResponse::body)
          .join();
    
        // Multiple libraries are available to parse the JSON response, e.g., gson (https://github.com/google/gson)
        var response = new Gson().fromJson(responseStr, Response.class);
      }
    
      static class Response {
        private double mass;
        private double exactMass;
        private String formula;
    
        // ... other fields
        // ... getters, setters
      }
    }

    How to achieve the best performance

    Coming soon...

    FAQ

    What if I lost my API key?

    In case you need a new API key, you have to unsubscribe from this product on AWS Marketplace page and subscribe again. This process removes your previous API key associated to your account and assign a new one.

    Can I own multiple API keys?

    No, you can only have one API key associated to your AWS account.

    Does subscribing to Chemaxon Calculators and Predictors cost any money?

    Subscribing and unsubscribing to the service is free of charge. We only charge you for the API calls you make.

    How much does an API call cost?

    Each chemical calculation API call has a different price based on how complex the calculation is. For the detailed list, see Pricing.