--- title: "Find Target stores near a location" method: GET path: "/target/stores" tags: ["target"] --- # Find Target stores near a location `GET /target/stores` ## Request - Base URL: `https://www.socialcrawl.dev/v1` - URL: `https://www.socialcrawl.dev/v1/target/stores` - Auth: API key in header `x-api-key` Returns Target stores near a ZIP code, city, or state, each with its store id, name, full address, phone number, distance from the searched location, open/closed status, timezone, and two weeks of daily opening hours. Store data changes rarely, so it is 1 credit and heavily cached. Note that Target's product pricing is national on this API, so a store id here is for store-locator use rather than for localising prices. ## Query parameters - `query` string, required ## Headers - `Cache-Control` string - `Idempotency-Key` string ## Response `200` Successful response - object - `success` boolean, required: Whether the request succeeded - `platform` string, required: Platform name - `endpoint` string, required: API endpoint path - `data` object, required: Platform-specific response data - `items` object[]: Array of canonical place wrappers ({ place }) - `place` object: Canonical Place object (physical/local business or hotel) - `id` string: Place ID (Google cid for a business, hotel_identifier for a hotel) - `name` string, nullable: Business / hotel name - `url` string, nullable: Website or canonical URL - `category` string, nullable: Primary category (e.g. "Coffee shop", "Hotel") - `rating` object: Aggregate rating (value + max) - `value` integer, nullable: Numeric at place.rating.value - `max` integer, nullable: Numeric at place.rating.max - `reviews_count` integer, nullable: Number of ratings - `price_level` string, nullable: Price band ("inexpensive" / "$$" / null) - `address` string, nullable: String at place.address - `phone` string, nullable: String at place.phone - `latitude` integer, nullable: Numeric at place.latitude - `longitude` integer, nullable: Numeric at place.longitude - `verified` boolean, nullable: Claimed-business flag (Google is_claimed) - `description` string, nullable: String at place.description - `image_urls` union: Union: string | array | null - string - string[] - `categories` string[], nullable: Array at place.categories - `hotel` object, nullable: Hotel-only richness (stars, amenities, review topics, prices); null for plain places - `stars` integer, nullable: Numeric at place.hotel.stars - `stars_description` string, nullable: String at place.hotel.stars_description - `check_in_time` string, nullable: String at place.hotel.check_in_time - `check_out_time` string, nullable: String at place.hotel.check_out_time - `amenities` object[], nullable: Array at place.hotel.amenities - `category` string, nullable: String at place.hotel.amenities.category - `name` string, nullable: String at place.hotel.amenities.name - `available` boolean, nullable: Boolean at place.hotel.amenities.available - `hint` string, nullable: String at place.hotel.amenities.hint - `review_topics` object[], nullable: Array at place.hotel.review_topics - `title` string, nullable: String at place.hotel.review_topics.title - `positive_score` integer, nullable: Numeric at place.hotel.review_topics.positive_score - `positive_count` integer, nullable: Numeric at place.hotel.review_topics.positive_count - `negative_count` integer, nullable: Numeric at place.hotel.review_topics.negative_count - `total_count` integer, nullable: Numeric at place.hotel.review_topics.total_count - `prices` object[], nullable: Array at place.hotel.prices - `title` string, nullable: String at place.hotel.prices.title - `price` integer, nullable: Numeric at place.hotel.prices.price - `currency` string, nullable: String at place.hotel.prices.currency - `url` string, nullable: String at place.hotel.prices.url - `official_site` boolean, nullable: Boolean at place.hotel.prices.official_site - `ext` object, nullable: Nested object: place.ext - `distance` integer, nullable: Numeric at place.ext.distance - `status` string, nullable: String at place.ext.status - `timezone` string, nullable: String at place.ext.timezone - `hours` object[], nullable: Array at place.ext.hours - `date` string, nullable: String at place.ext.hours.date - `day_name` string, nullable: String at place.ext.hours.day_name - `is_open` boolean, nullable: Boolean at place.ext.hours.is_open - `opens_at` string, nullable: String at place.ext.hours.opens_at - `closes_at` string, nullable: String at place.ext.hours.closes_at - `place_id` string, nullable: String at place.ext.place_id - `attributes` string, nullable: Leaf at place.ext.attributes - `rating_distribution` string, nullable: Leaf at place.ext.rating_distribution - `people_also_search` object[], nullable: Array at place.ext.people_also_search - `cid` string, nullable: String at place.ext.people_also_search.cid - `title` string, nullable: String at place.ext.people_also_search.title - `rating` object, nullable: Nested object: place.ext.people_also_search.rating - … - `menu_url` string, nullable: String at place.ext.menu_url - `domain` string, nullable: String at place.ext.domain - `maps_url` string, nullable: String at place.ext.maps_url - `rank` integer, nullable: Numeric at place.ext.rank - `city` string, nullable: String at place.ext.city - `postal_code` string, nullable: String at place.ext.postal_code - `region` string, nullable: String at place.ext.region - `country_code` string, nullable: String at place.ext.country_code - `next_cursor` string, nullable: Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results. - `total` integer, nullable: Total number of matching results, when the upstream provides a count. Omitted otherwise. - `dropped` integer, required: Number of upstream list items dropped because they could not be repaired to the endpoint schema. Valid list responses include 0. - `_warnings` string[]: Non-fatal notices about this response (field-map drift, clamped computed values). Advisory only: its presence never means the request failed. Omitted entirely when there is nothing to report, so treat absent as 'no warnings'. - `credits_used` integer, required: Number of credits consumed - `credits_remaining` integer, nullable, required: Current account balance, or null when this response could not establish one. Free cache hits always return null because they do not establish an authoritative post-request balance. An idempotency replay also returns null when its current-balance lookup fails. It is never a fabricated zero, so a zero here means the account really is empty. The authoritative reading is the one on a billed response, which comes straight from the deduction. - `request_id` string, required: Unique request identifier for support - `cached` boolean, required: Whether the response was served from cache - `idempotent_replay` boolean: True only when this response is an idempotency replay - `meta` object: Optional. Present only when this call completed a pattern that one other call does more cheaply or in one step, at most once per pattern per API key per day. Send the header `X-SocialCrawl-Hints: off` to never receive it. - `hint` object: One suggestion: what to call instead and why, with the price when the suggested call costs more than the calls it replaces. - `code` string: creator_card | batch_profiles | search_multi | incremental_sync | comment_labels | search_repeat - `message` string: One sentence for a person or an agent to read. - `method` string: GET or POST. - `path` string: The call the hint points to. - `pagination` object, required: Cursor state for this page. Present on every list response. - `next_cursor` string, nullable, required: Opaque token to send back as `cursor` for the next page, or null at end-of-list. Pass it back verbatim; never decode or trim it. - `has_more` boolean, required: Explicit stop signal. Prefer this over inspecting next_cursor or comparing against total. - `page_size` integer, required: Number of items in THIS page. - `stopped_at` 'since' | 'known_id' | 'end' | 'null', nullable: Present only when the request sent `since` or `stop_at_id`. Why the walk stopped: `since` (this page reached a post older than the date), `known_id` (this page reached the post you already hold), `end` (the list ran out first), or null (not yet, keep walking with `next_cursor`). ## Other responses - `400`: Invalid request - missing or malformed parameters - `401`: Unauthorized - missing or invalid API key - `402`: Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit - `404`: Not found - the endpoint does not exist, or the requested resource was not found upstream - `405`: Method not allowed - wrong HTTP verb for this endpoint - `409`: Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation - `410`: Gone - the discover run's retention passed and its rows were deleted; start a new run - `413`: Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling - `422`: Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC) - `429`: Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits. - `500`: Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit - `502`: Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge - `503`: Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge - `504`: Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After --- [API](https://skmtc.dev/socialcrawl/apis/socialcrawl-api.md) · [All operations](https://skmtc.dev/socialcrawl/apis/socialcrawl-api/llms.txt) · [OpenAPI document](https://skmtc.dev/socialcrawl/apis/socialcrawl-api/revisions/a0ad2511004a?raw)