# Grainger Search

## Overview

| Property | Value |
|----------|-------|
| **Status** | active |
| **Method** | `GET` |
| **Endpoint** | `/v2/grainger/search` |
| **Base URL** | `https://api.piloterr.com` |
| **Credit Cost** | 2 credits per call |
| **Documentation** | https://www.piloterr.com/library/grainger-search |

## Description

Search Grainger US or Canada by keyword, category URL or SKU. Returns product listings, category branches and suggestions via browser rendering.

## Authentication

- **Key Name:** `x-api-key`
- **Location:** HTTP Header
- **Get an API key:** https://app.piloterr.com/register

## Example Request

```bash
curl --location --request GET 'https://api.piloterr.com/v2/grainger/search' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY'
```

## Example Response

### Keyword carolina (category branches)

```json
{
  "url": "https://www.grainger.com/search?searchQuery=carolina&searchBar=true",
  "query": "carolina",
  "region": "com",
  "categories": [
    {
      "url": "https://www.grainger.com/category/safety/footwear-footwear-accessories/safety-toe-work-boots-shoes",
      "title": "Close Match Safety-Toe Work Boots & Shoes"
    },
    {
      "url": "https://www.grainger.com/category/safety/footwear-footwear-accessories/plain-toe-work-boots-shoes",
      "title": "Plain-Toe Work Boots & Shoes"
    }
  ],
  "total_results": 0
}
```

### SKU 3FRU1 redirected to product

```json
{
  "url": "https://www.grainger.com/search?searchQuery=3FRU1&searchBar=true",
  "query": "3FRU1",
  "region": "com",
  "results": [
    {
      "sku": "3FRU1",
      "url": "https://www.grainger.com/product/PENTAIR-PENTEK-Water-Filter-Cartridge-5-micron-3FRU1",
      "price": 6.67,
      "title": "PENTAIR/PENTEK Water Filter Cartridge: 5 micron, Melt Blown, 2 gpm, Polypropylene",
      "currency": "USD"
    }
  ],
  "total_results": 1
}
```

## Documentation

## Overview
The **Grainger Search** endpoint searches Grainger US (`grainger.com`) or Canada (`grainger.ca`) by keyword, category URL or path.

It returns product listings when available, plus category branches and suggested products. Browser rendering is used because Grainger pages need JavaScript and scroll to load listings.

Costs **2 credits** per call.

## Quickstart
```
GET https://api.piloterr.com/v2/grainger/search?query=carolina
GET https://api.piloterr.com/v2/grainger/search?query=carolina&region=ca
GET https://api.piloterr.com/v2/grainger/search?query=https://www.grainger.com/category/abrasives
GET https://api.piloterr.com/v2/grainger/search?query=3FRU1
```

## Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `query` | string | yes | Keyword, search/category URL, category path, or SKU |
| `region` | string | no | `com` (default, USD) or `ca` (CAD). Detected from a full URL |
| `return_page_source` | boolean | no | Return rendered HTML instead of JSON (default: `false`) |

## Regions
| `region` | Host | Currency |
|---|---|---|
| `com` | www.grainger.com | USD |
| `ca` | www.grainger.ca | CAD |

## Response fields
| Field | Type | Description |
|---|---|---|
| `region` | string | `com` or `ca` |
| `query` | string | Search keyword when present in the URL |
| `url` | string | Resolved page URL |
| `total_results` | number | Product count when available |
| `results` | array | Product listings (`sku`, `title`, `url`, `price`, `currency`) |
| `categories` | array | Category branches (`title`, `url`) when the page shows them |
| `suggested_products` | array | Suggested products when there is no direct match |
| `no_results` | boolean | `true` when the page reports an empty search |

Empty values are omitted from the JSON response.

## Error codes
| Code | Meaning |
|---|---|
| `400` | Empty or invalid `query` |
| `404` | Rendered page has no usable data |
| `500` | Rendering failed |

## Related endpoints
- [Grainger Product](https://www.piloterr.com/library/grainger-product)