Introduction

Web Data Platform Walmart is an API that allows retrieving publicly available data from Walmart. The API can return pre-scraped data via Data API or scrape items on demand via Bulk Refresh API. Pre-scraped data is updated on regular basis. The API returns clean, structured JSON. Pre-scraped data can be retrieved using pagination, downloading the whole dataset via provided links, or uploading it to your cloud storage. On-demand data can be uploaded to your cloud storage in JSONL format and can also be downloaded via provided links.

On-demand data via Bulk Refresh API can take up to 24 hours to complete, depending on the request size and scraping complexity on a given day.

Data API

POST /products

curl -X POST "https://api.datasets.oxylabs.io/v1/walmart/products?api_key=<API_KEY>" -H "Content-Type: application/json" -d '{"ids": ["1BA01ZVLPJIW", "1BA01ZVEPJIW"]}

Query Parameters

Parameter	Description	Required
`ids`	Product IDs according to Walmart	Either `ids` or `category_ids` should be used as input.
`category_ids`	Category IDs according to Walmart	Either `ids` or `category_ids` should be used as input.

The response is paginated, total_pages indicate how many pages there are. The following pages can be retrieved using page parameter via Dataset endpoint. The response also containts items_found, which represent the number of products matching the query criteria.

GET /seller/products

curl "https://api.datasets.oxylabs.io/v1/walmart/seller/products?api_key=<API_KEY>&category_id=11044954"

Query Parameters

Parameter	Description	Required
`category_id`	Category ID according to Walmart. For example, `category_id=11044954`. The full list of available categories for Walmart.com can be retrieved via Categories endpoint. Either `category_id` or `category_path` should be used as input.	Yes
`category_path`	Category path according to Walmart. For example, `category_path=11044954_11044955_11044956`. The full list of available categories for Walmart.com can be retrieved via Categories endpoint. Either `category_id` or `category_path` should be used as input.	No
`record_refreshed_at_min` / `record_refreshed_at_max`	Minimum and maximum date of when the product data was last refreshed.	No
`price_min` / `price_max`	Minimum and maximum price of the products to return.	No
`rating_min` / `rating_max`	Minimum and maximum rating of the products to return.	No
`condition`	Condition of the products to return. Available values: `new`, `used`.	No
`is_bestseller`	Whether to return only bestsellers. Available values: `true`, `false`.	No
`page`	Page number to return. Default value is `1`.	No

The response is paginated, the following pages can be retrieved using page parameter.

GET /products/price_history

curl "https://api.datasets.oxylabs.io/v1/walmart/products/price_history/{product_id}?api_key=<API_KEY>"

Query Parameters

Parameter	Description	Required
`product_id`	Product ID according to Walmart.	No

GET /additional_sellers

curl "https://api.datasets.oxylabs.io/v1/walmart/additional_sellers?api_key=<API_KEY>&product_id=513411235"

Response:

{
  "first_seen_at": "2024-12-02T11:43:15+00:00",
  "options": [
    {
      "add_on_services": [],
      "discounts": [],
      "fullfilment_badge": null,
      "fullfilment_options": [
        {
          "available_quantity": 15,
          "in_stock": true,
          "intent": "true",
          "max_order_quantity": 12,
          "order_limit": 12,
          "selected": false,
          "speed_details": {
            "delivery_date": "2024-12-10T22:59:00.000Z",
            "free_fulfillment": true,
            "fulfillment_badge": null,
            "fulfillment_price": {
              "price": null
            },
            "w_plus_eligible": false
          },
          "type": "SHIPPING"
        },
        {
          "available_quantity": null,
          "in_stock": false,
          "intent": "false",
          "max_order_quantity": null,
          "order_limit": null,
          "selected": false,
          "speed_details": {
            "delivery_date": null,
            "free_fulfillment": null,
            "fulfillment_badge": null,
            "fulfillment_price": {
              "price": null
            },
            "w_plus_eligible": null
          },
          "type": "PICKUP"
        },
        {
          "available_quantity": null,
          "in_stock": false,
          "intent": "false",
          "max_order_quantity": null,
          "order_limit": null,
          "selected": false,
          "speed_details": {
            "delivery_date": null,
            "free_fulfillment": null,
            "fulfillment_badge": null,
            "fulfillment_price": {
              "price": null
            },
            "w_plus_eligible": null
          },
          "type": "DELIVERY"
        }
      ],
      "fullfilment_type": "MARKETPLACE",
      "in_stock": true,
      "main_image": "https://i5.walmartimages.com/seo/SSG-BSN-The-Shooter-Ring-Basketball_cc988db0-89c9-48fc-9eca-d9915806874f.6c814d3715e251f7949f96efda6f51aa.jpeg",
      "offer_id": "13F47195A8D34DC192C2E2AFEB8ECCB0",
      "offer_type": "ONLINE_ONLY",
      "price_info": {
        "currency_symbol": "$",
        "initial_price": null,
        "price": 53.2,
        "unit_price": null
      },
      "product_id": 4016344,
      "promo_discount": null,
      "return_policy": {
        "free_returns": true,
        "return_policy_text": "Free 30-day returns",
        "return_window": 30,
        "return_window_unit": "Day",
        "returnable": true
      },
      "rewards": null,
      "seller_display_name": "VirVentures",
      "seller_id": "184A332693BE4609ABAAA0F1189BFF12",
      "seller_name": "Vir Ventures Inc.",
      "seller_type": "EXTERNAL"
    }        
  ],
  "product_id": 513411235,
  "record_refreshed_at": "2024-12-02T11:43:15+00:00",
  "total_sellers": 4,
}

Query Parameters

Parameter	Description	Required
`product_id`	Product ID according to Walmart.	No

The response is paginated, total_pages indicate how many pages there are. The following pages can be retrieved using page parameter. The response also containts items_found, which represent the number of products matching the query criteria.

GET /categories

curl "https://api.datasets.oxylabs.io/v1/walmart/categories?api_key=<API_KEY>"

Walmart has a specific product hierarchy. To make finding the right data easier, Datasets API provides the /categories endpoint that allows to retrieve category_id and category_path values of all discovered Walmart.com categories.

The API provides a category tree (breadcrumbs), which describes the hierarchical relationship between categories using a level attribute.

category_id and category_path values returned by this endpoint can be used in category/products endpoint to retrieve all items in the specified Walmart category.

Query Parameters

Parameter	Description	Required
`page`	Page number to return. Default value is `1`.	No

GET / POST /dataset

curl "https://api.datasets.oxylabs.io/v1/dataset?api_key=<API_KEY>&dataset_id=2pF8MrlxPNO6ilMO"

curl -X POST "https://api.datasets.oxylabs.io/v1/dataset?api_key=<API_KEY>" -H "Content-Type: application/json" -d '{"dataset_id": "2pF8MrlxPNO6ilMO", "type": "s3", "bucket": "your-bucket-name", "path": "your-path"}'

All API endpoints will return dataset_id. This ID then can be used to download the full dataset of that matching query. For example, you asked to find all products from "category_id": 11044954 using /category/products endpoint. The API found 123,293 products that match your query. You can proceed to download these records using paginanation feature using the same /category/products endpoint, or you can download the whole dataset of 123,293 items all at once by sending dataset_id from the response to the /dataset endpoint.

Download dataset directly as a file (GET)

Parameter	Description	Required	Available Values
`dataset_id`	Dataset ID from previous API response	Yes	-

Upload dataset to cloud storage (POST)

To upload the dataset to your bucket, you can use the POST request with the same endpoint. You will need to authorize our credentials to your bucket.

Parameter	Description	Required	Available Values
`dataset_id`	Dataset ID from previous API response	Yes	-
`type`	Bucket type	Yes	`s3`, `gcs`
`bucket`	Your bucket name	Yes	-
`path`	Path within your bucket to upload the dataset	Yes	-

Cloud Storage Permissions

Amazon S3

To enable uploads to your S3 bucket:

Go to AWS S3 Console
Navigate to S3 > Storage > Bucket Name
Go to Permissions > Bucket Policy
Apply the bucket policy replacing YOUR_BUCKET_NAME with your bucket name

Google Cloud Storage

To enable uploads to your GCS bucket:

Create a custom role with the storage.objects.create permission
Assign it to the service account: oxylabs-datasets-uploader@oxyds-database-api-prod.iam.gserviceaccount.com

Bulk Refresh API

POST /scrape

curl -X POST "https://api.datasets.oxylabs.io/v1/walmart/scrape?api_key=<API_KEY>" \
-H "Content-Type: application/json" \
-d '{
  "dataset": "category_products",
  "categories": [
    {
      "category_path": "5440_202072_1416135",
      "store_id": "718",
      "zip_code": "33823",
      "filters": [
        {
          "key": "brand",
          "value": ["ARM & HAMMER", "Hartz"]
        },
        {
          "key": "exclude_oos",
          "value": "Show available items only"
        }
      ]
    }
  ],
  "max_pages": 5,
  "discovery": true,
  "html": true,
  "destination": {
    "target": "S3",
    "bucket": "my-bucket",
    "prefix": "walmart-data"
  }
}'

Request Parameters

Parameter	Description	Required
`dataset`	Dataset type. Available values: `searches`, `category_products`, `products`.	Yes
`categories`	Array of category objects. Each object can include:	Required if `dataset` is `category_products`
`category_path`	Category path (e.g., `5440_202072_1416135`). Find existing category paths using categories endpoint.	Yes
`store_id`	Store ID for location-specific data	No
`zip_code`	ZIP code for location-specific data	No
`filters`	Array of filter objects with `key` and `value` properties	No
`products`	Array of product objects. Each object can include:	Required if `dataset` is `products`
`id`	Product ID (e.g., `513411235`)	Yes
`store_id`	Store ID for location-specific data	No
`zip_code`	ZIP code for location-specific data	No
`keywords`	Array of search objects. Each object can include:	Required if `dataset` is `searches`
`keyword`	Search term (e.g., `adidas`)	Yes
`store_id`	Store ID for location-specific data	No
`zip_code`	ZIP code for location-specific data	No
`filters`	Array of filter objects with `key` and `value` properties	No
`input_type`	Product ID type, either Walmart Product ID or GTIN. Available values: `walmart_product_id`, `gtin`. If GTIN is provided, we try to find a corresponding Walmart Product ID on our end and use it for scraping. Default is `walmart_product_id`.	Required if `dataset` is `products`
`max_pages`	Maximum number of pages to scrape per input (applies to `category_products` and `searches` datasets)	No
`discovery`	Enable deep product discovery (applies to `category_products` only)	No
`html`	Return raw HTML or JSON alongside parsed data	No
`destination`	Cloud storage configuration for results	No
`target`	Cloud storage provider. Available values: `GCP`, `AWS`.	No
`bucket`	Storage bucket name.	No
`prefix`	Path prefix within bucket.	No

Filter Examples

The filters array allows you to narrow down results using various criteria available on Walmart.com.

Common filter keys include: - brand - Filter by one or more brand names (array of strings) - exclude_oos - Filter out of stock items ("Show available items only") - price_min / price_max - Filter by price range - rating_min - Filter by minimum rating

Example Requests

// Category Products Request
{
  "dataset": "category_products",
  "categories": [
    {
      "category_id": "5440_202072_1416135",
      "store_id": "718",
      "zip_code": "33823",
      "filters": [
        {
          "key": "brand",
          "value": ["ARM & HAMMER", "Hartz"]
        },
        {
          "key": "exclude_oos",
          "value": ["Show available items only"]
        }
      ]
    },
    {
      "category": "3944_1060825_2489948",
      "zip_code": "60653",
      "filters": [
        {
          "key": "brand",
          "value": ["TCL"]
        }
      ]
    }
  ],
  "max_pages": 5
}

// Products Request
{
  "dataset": "products",
  "products": [
    {
      "id": "513411235",
      "store_id": "718",
      "zip_code": "33823"
    },
    {
      "id": "513411235",
      "zip_code": "60653"
    }
  ],
  "max_pages": 5
}

// Searches Request
{
  "dataset": "searches",
  "keywords": [
    {
      "keyword": "adidas",
      "store_id": "718",
      "zip_code": "33823",
      "filters": [
        {
          "key": "brand",
          "value": ["ARM & HAMMER", "Hartz"]
        },
        {
          "key": "exclude_oos",
          "value": "Show available items only"
        }
      ]
    },
    {
      "keyword": "nike",
      "zip_code": "60653",
      "filters": [
        {
          "key": "brand",
          "value": ["TCL"]
        }
      ]
    }
  ],
  "max_pages": 5
}

The scrape endpoint supports uploading results to Amazon S3 or Google Cloud Storage. See the cloud storage permissions section below for setup instructions.

Cloud Storage Permissions

Amazon S3

To enable uploads to your S3 bucket:

Go to AWS S3 Console
Navigate to S3 > Storage > Bucket Name
Go to Permissions > Bucket Policy
Apply the bucket policy replacing YOUR_BUCKET_NAME with your bucket name

Google Cloud Storage

To enable uploads to your GCS bucket:

Create a custom role with the storage.objects.create permission
Assign it to the service account: oxylabs-datasets-uploader@oxyds-database-api-prod.iam.gserviceaccount.com

Utility Endpoints

GET /id_lookup

curl "https://api.datasets.oxylabs.io/v1/id_lookup?gtin=1234567890&api_key=<API_KEY>"

Response: { "gtin": "1234567890", "walmart_sku": "44442233" }

Query Parameters

Parameter	Description	Required
`gtin`	GTIN to lookup	Yes

GET /users/stats

curl "https://api.datasets.oxylabs.io/v1/users/stats?api_key=<API_KEY>"

Response:

{
  "data": [
    {
      "date": "2024-01-01",
      "credits_used": 3600
    },
    {
      "date": "2024-01-02",
      "credits_used": 7600
    },
    {
      "date": "2024-01-03",
      "credits_used": 720
    }
  ]
}

Query Parameters

Parameter	Description	Required
`api_key`	Your API key	Yes