How to Use the AWS Price List API with Examples

The AWS Price List API provides a convenient way to get the price list of products and services. In this post, we'll show you how to use the API with examples. We'll also discuss some of key the features of the API.

Using the AWS Price List API, you can programmatically query the pricing for AWS services and receive results in JSON and CSV format. The original version of this API introduced in 2015, which is still accessible and now referred to as the AWS Price List Bulk API, is based on a simple URL format to obtain pricing information. This version is accessible on the following endpoing:

• https://pricing.us-east-1.amazonaws.com

The newer version announced in 2017, referred to as the AWS Price List Query API, is a full rest API enabling querying and metadata functions. The AWS Price List Query API has two endpoints:

• https://api.pricing.us-east-1.amazonaws.com
• https://api.pricing.ap-south-1.amazonaws.com

Note the subtle difference in the domain between the older and newer versions of the API.

In this article, we'll show you how to use both versions of the AWS Price List API to get pricing information for AWS services, using a few different example scenarios.

AWS Price List Bulk API

The 2015 AWS Price List API is a publicly accessible resource that enables you to query the pricing of AWS products using a simple URL structure. For example, to get a full listing of all the available AWS price lists on the API in all regions you could use the following URL:

https://pricing.us-east-1.amazonaws.com/offers/v1.0/aws/index.json

This will result in a large JSON file in the following format listing all the available services as "offerCode" along with URLs to get pricing for that service:

{
 "formatVersion" : "v1.0",
 "disclaimer": "This pricing list is for informational purposes only. All prices are subject to the additional terms included in the pricing pages on http://aws.amazon.com. All Free Tier prices are also subject to the terms included at https://aws.amazon.com/free/",
 "publicationDate" : "2022-08-16T06:15:19Z",
 "offers": {
  "comprehend" : {
   "offerCode" : "comprehend",
   "versionIndexUrl" : "/offers/v1.0/aws/comprehend/index.json",
   "currentVersionUrl" : "/offers/v1.0/aws/comprehend/current/index.json",
   "currentRegionIndexUrl" : "/offers/v1.0/aws/comprehend/current/region_index.json"
  },
  "AmazonMWAA" : {
   "offerCode" : "AmazonMWAA",
   "versionIndexUrl" : "/offers/v1.0/aws/AmazonMWAA/index.json",
   "currentVersionUrl" : "/offers/v1.0/aws/AmazonMWAA/current/index.json",
   "currentRegionIndexUrl" : "/offers/v1.0/aws/AmazonMWAA/current/region_index.json"
  },
...
 }
}

To get pricing for Amazon EC2 instances available in US East (N. Virginia), you would use the following URL:

https://pricing.us-east-1.amazonaws.com/offers/v1.0/aws/AmazonEC2/current/us-east-1/index.json

To get the pricing for Amazon S3 storage in US East (N. Virginia), you would use the following URL:

https://pricing.us-east-1.amazonaws.com/offers/v1.0/aws/AmazonS3/current/us-east-1/index.json

To query for different regions, you would change the region code in the path segment (not the subdomain). For example, to get the products for Amazon EC2 in EU (Ireland), you would use the following URL:

https://pricing.us-east-1.amazonaws.com/offers/v1.0/aws/AmazonEC2/current/eu-west-1/index.json

The AWS Price List Service API returns pricing information in JSON format. The following is an example of the JSON returned for the Amazon S3 offers in US East (N. Virginia):

{
 "formatVersion" : "v1.0",
 "disclaimer": "This pricing list is for informational purposes only. All prices are subject to the additional terms included in the pricing pages on http://aws.amazon.com. All Free Tier prices are also subject to the terms included at https://aws.amazon.com/free/",
 "offerCode" : "AmazonS3",
 "version" : "20220518004158",
 "publicationDate" : "2022-05-18T00:41:58Z",
 "products" : {
  "Z8X7XRC6YMB3B8CX": {
   "sku" : "Z8X7XRC6YMB3B8CX",
   "attributes" : {
    "servicecode" : "AmazonS3",
    "transferType" : "InterRegion Inbound",
    "fromLocation" : "Asia Pacific (Singapore)",
    "fromLocationType" : "AWS Region",
    "toLocation" : "US East (N. Virginia)",
    "toLocationType" : "AWS Region",
    "usagetype" : "USE1-APS1-S3RTC-In-Bytes",
    "operation" : "",
    "fromRegionCode" : "ap-southeast-1",
    "servicename" : "Amazon Simple Storage Service",
    "toRegionCode" : "us-east-1"
   }
...
},
"terms" : {
  "OnDemand" : {
   "UMHS42HQRXCX35Z3": {
    "UMHS42HQRXCX35Z3.JRTCKXETXF" : {
     "offerTermCode" : "JRTCKXETXF",
     "sku" : "UMHS42HQRXCX35Z3",
     "effectiveDate" : "2022-05-01T00:00:00Z",
     "priceDimensions" : {
      "UMHS42HQRXCX35Z3.JRTCKXETXF.6YS6EN2CT7" : {
       "rateCode" : "UMHS42HQRXCX35Z3.JRTCKXETXF.6YS6EN2CT7",
       "description": "$0.015 per GB - US East (N. Virginia) Data Transfer for Replication Time Control to Asia Pacific (Hong Kong)",
       "beginRange" : "0",
       "endRange" : "Inf",
       "unit" : "GB",
       "pricePerUnit" : {
        "USD" : "0.0150000000"
       },
       "appliesTo" : [ ]
      }
     },
     "termAttributes" : { }
    }
   },
...
  }
 },
 "attributesList" : { }
}

You can of course obtain JSON files from the API with wget on the command line and parse them on your end with a tool like jq. For example to find out the SKUs for all the EC2 instance types currently available in the Canada (Central) region:

wget -q -O - https://pricing.us-east-1.amazonaws.com/offers/v1.0/aws/AmazonEC2/current/ca-central-1/index.json | jq -r '.products[].sku'

...
7R9W3YZ4YJH77D75
RHRU82RD2NQANEJZ
MGM5TKXXZ2H7RTF8
BMKAQTM5QK7AP8JR
TNFSUH8ZK5TJAGVF
8VJAHYMURVF6PMCY
QW2NUY7EYTJU53G7
YUU2G2Y46PPDT4GG
... etc.

AWS Price List Query API

In 2017 AWS added functionality to the API enabling granular server-side filtering. The new API requires an AWS account and credentials that permit pricing actions as shown in this IAM policy:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "pricing:DescribeServices",
        "pricing:GetAttributeValues",
        "pricing:GetProducts"
      ],
      "Resource": [
        "*"
      ]
    }
  ]
}

The API offers three functions:

DescribeServices

With this function, you can obtain attribute keys that you can use in subsequent API calls to build your filtering request.

GetAttributeValues

If you pass one of the attribute keys from DescribeServices, you will receive all the possible values for that key.

GetProducts

This is the real meat and potatoes of the API, returning all the filtered products and their pricing.

The new API is accessible using command line tools and the AWS SDKs for Python, Node.js and others.

AWS Price List Service API Example

Most of the time today when using an API to obtain AWS pricing you will be using the query API and thinking in terms of services, so let's look at an AWS price list service API example.

To get a service description for ElasticMapReduce with the DescribeServices function, you make a POST request to the endpoint with the following syntax:

{
  "FormatVersion": "aws_v1",
  "MaxResults": 100,
  "NextToken": "string",
  "ServiceCode": "ElasticMapReduce"
}

It's worth noting that none of those parameters are required to make the post request, but to narrow down to a specific service you will need at least the ServiceCode.

You can try a basic curl request to get pricing with a basic JSON filter:

curl -v https://api.pricing.us-east-1.amazonaws.com \
  --aws-sigv4 "aws:amz:us-east-1:pricing" \
  --user "$AWS_ACCESS_KEY_ID:$AWS_SECRET_ACCESS_KEY" \
  -H 'Content-Type: application/x-amz-json-1.1' \
  -H 'X-Amz-Target: AWSPriceListService.DescribeServices' \
  -d '{"ServiceCode": "ElasticMapReduce"}'

The process is the same for GetAttributeValues and GetProducts. Of course, the AWS SDKs make interacting with the API much easier.

In Python, the same basic operation can be done with the following:

import boto3
from botocore.config import Config

my_config = Config(
    region_name = 'us-east-1',
    signature_version = 'v4',
    retries = {
        'max_attempts': 10
    }
)

client = boto3.client('pricing', config=my_config)

response = client.describe_services(
    ServiceCode='ElasticMapReduce'
)

The response for the above looks something like this:

{
    "Services": [
        {
            "ServiceCode": "ElasticMapReduce",
            "AttributeNames": [
                "productFamily",
                "softwareType",
                "instanceType",
                "termType",
                "usagetype",
                "locationType",
                "instanceFamily",
                "meterunit",
                "compute",
                "regionCode",
                "servicecode",
                "pricingUnit",
                "location",
                "servicename",
                "operation",
                "computeprovider"
            ]
        }
    ],
    "FormatVersion": "aws_v1",
    "ResponseMetadata": {
        "RequestId": "request-id",
        "HTTPStatusCode": 200,
        "HTTPHeaders": {
            "x-amzn-requestid": "request-id",
            "content-type": "application/x-amz-json-1.1",
            "content-length": "312",
            "date": "Tue, 16 Aug 2022 14: 36: 59 GMT"
        },
        "RetryAttempts": 0
    }
}

For additional information and examples, be sure to see the official AWS documentation for the API.

If you need help interacting with the AWS Price List service API, please don't hesitate to contact us. Our team of AWS experts will be happy to assist you in getting the most out of this powerful tool. Thanks for reading!