# Target (/docs/target)

Target product, review, category and store data through one unified API

Target.com product detail, customer reviews, category browsing, and store locations behind the same canonical commerce schema as Amazon, Walmart and Google Shopping, so one parser handles all of them.

Base URL: `/v1/target/...`

Products are keyed on the **TCIN**, Target's catalogue id and the number at the end of any product URL. In `target.com/p/beats-solo-buds/-/A-92148487` the TCIN is `92148487`.

  There is no Target keyword search here, and that is deliberate. Target's own
  search returns at most 24 products, ignores the page parameter, and answers a
  query that matches nothing with 24 unrelated products rather than an empty
  list. Browse the category tree instead.

## Quickstart

### Walk the category tree to find TCINs

`categories` returns the whole taxonomy for 1 credit and caches hard. Feed a node id to `category` to page through its products with real prices, 24 at a time.

```bash title="cURL"
curl "https://www.socialcrawl.dev/v1/target/categories" \
  -H "x-api-key: YOUR_API_KEY"

curl "https://www.socialcrawl.dev/v1/target/category?category_id=hz89j" \
  -H "x-api-key: YOUR_API_KEY"
```

### Read a product and its reviews

Already holding a TCIN? Start here.

```bash title="cURL"
curl "https://www.socialcrawl.dev/v1/target/product?tcin=92148487" \
  -H "x-api-key: YOUR_API_KEY"

curl "https://www.socialcrawl.dev/v1/target/reviews?tcin=92148487" \
  -H "x-api-key: YOUR_API_KEY"
```

## Browse

| Endpoint                    | Credits | What it returns                                                                                        | Key parameters                   |
| --------------------------- | ------- | ------------------------------------------------------------------------------------------------------ | -------------------------------- |
| `GET /v1/target/categories` | 1       | The browse taxonomy: node id, display name, parent id, canonical URL, hero image                       | none                             |
| `GET /v1/target/category`   | 5       | 24 products a page with title, brand, price, regular price, rating, images, highlight bullets and TCIN | `category_id` (required), `page` |

Category node ids come from `categories`, and also appear in the category URLs on target.com as the `N-<id>` segment. If you specifically need keyword matching, [`/v1/search/everywhere`](/docs/search/everywhere.md) runs a cross-source sweep instead.

## Products and reviews

| Endpoint                 | Credits | What it returns                                                                                                                                                           | Key parameters            |
| ------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
| `GET /v1/target/product` | 5       | Title, brand, description, highlight bullets, current and regular price, rating with its 1-5 distribution, review count, image gallery, colour and size variations, stock | `tcin` (required)         |
| `GET /v1/target/reviews` | 5       | 10 reviews a page with full text, star rating, reviewer nickname, date, helpful votes, verified-purchase flag, photos                                                     | `tcin` (required), `page`, `label`, `judgments` |

If what you want is the rating breakdown rather than the review text, call `product` and read `product.ext.rating_distribution`. It carries the same 1 to 5 star counts in a single call rather than one call per ten reviews.

```json title="JSON"
"ext": {
  "rating_distribution": {
    "star_1": 549, "star_2": 149, "star_3": 124, "star_4": 148, "star_5": 932
  }
}
```

## Stores

| Endpoint                | Credits | What it returns                                                                                                  | Key parameters     |
| ----------------------- | ------- | ---------------------------------------------------------------------------------------------------------------- | ------------------ |
| `GET /v1/target/stores` | 1       | Nearby stores with store id, name, address, phone, distance, open status, timezone, and two weeks of daily hours | `query` (required) |

`query` takes a ZIP code (`10001`), a city (`Austin`), or a state. It is 1 credit because store data barely changes and caches hard. The store-locator extras ride on `place.ext`:

```json title="JSON"
"ext": {
  "distance": 0.37,
  "status": "Open",
  "timezone": "America/New_York",
  "hours": [
    { "date": "2026-07-27", "day_name": "Monday", "is_open": true,
      "opens_at": "08:00:00", "closes_at": "23:00:00" }
  ]
}
```

## All endpoints

## Platform notes

**Target pricing is national.** Unlike Walmart, Target's product endpoint reports the same price whatever store is asked for, so there is no store or ZIP parameter here. Treat `price.current` as catalogue pricing rather than shelf pricing, and treat a store id from `stores` as store-locator data rather than a price selector.

**A variant TCIN resolves to its parent product.** Target rolls colours and sizes up, so asking for `92146817` (Matte Black) returns the parent product `92148487`, whose payload describes the family. `product.id` always carries the id of the product the payload actually describes, and `product.ext.requested_id` carries the id you asked for whenever the two differ, so the round trip is never lost. Colour and size options come back in `product.variations`, each with its own TCIN.

**De-duplicate a category crawl by `product.id`.** Target's category ordering shifts between calls, so consecutive pages occasionally repeat a handful of products. We measured 0 repeats one morning and 4 of 24 the same afternoon on the identical category. Every row carries a stable id, so a `Set` is all it takes.

**Category ratings are half-populated.** Roughly half of category rows carry a rating and the rest are null. That reflects Target's own data rather than an omission here; read the rating from `product` when you need it on every row.

**Review pagination is deterministic.** Review pages do not overlap and the review total is exact, so a full crawl terminates cleanly: pass the returned `pagination.next_cursor` back as `cursor` until `has_more` is `false`. Page size is fixed upstream at 10 and cannot be raised.

**Ratings and reviews are two different numbers.** `product.rating.count` is the number of people who left a star rating. `reviews_count` is the number who wrote review text, and it is the same population `reviews` paginates over. On a typical product the first is two to three times the second. Both are reported exactly as Target reports them; neither is an estimate.

**Stores have no coordinates.** Target publishes none, so `latitude` and `longitude` are null rather than guessed. Geocode the returned address if you need them.

**US only.** Prices are US dollars and there is no marketplace selector. Empty results and not-found TCINs are refunded automatically and never billed.

## Labels

`/v1/target/reviews` labels each review by default, at no extra credit: `sentiment` (read from the words, never the stars, with `rating_mismatch` when the two clearly disagree) and `issue` (the main problem the review reports) on `computed.labels`. Send `judgments=off` for the page without them. See [Labels](/docs/labels.md) for the field shapes and the labels you can add with `label=`, such as `label=reports&reports=the battery drains quickly`.

## Next steps

- [Pagination](/docs/pagination.md): The universal cursor, and how to walk a category to the end.
- [Credits](/docs/credits.md): What each tier costs, and which failures are refunded.
- [API reference](/docs/api-reference.md): Every Target parameter and response field.
- [Walmart](/docs/walmart.md): The same shapes for walmart.com, with store-level pricing.
- [Amazon](/docs/amazon.md): Keyword search, reviews and competing seller offers.