HomeGoods APIhomegoods.com ↗
Find HomeGoods store locations across the US. Search by zip, city, or coordinates. Get hours, addresses, phone numbers, and services for any store.
What is the HomeGoods API?
The HomeGoods API provides 3 endpoints to search, retrieve, and list HomeGoods retail store locations across the United States. Use search_stores to find up to 25 nearby stores by zip code, city name, or lat/lng coordinates, or call get_store_details to pull a specific store's phone number, daily hours, current open/closed status, and available services by store ID.
curl -X GET 'https://api.parse.bot/scraper/d848768c-bd78-439f-be44-3e8e181da592/search_stores?limit=5&latitude=40.7486&location=10001&longitude=-73.994' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace homegoods-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
from parse_apis.homegoods_store_finder_api import HomeGoods, Store, StoreSummary, State, StoreNotFound
client = HomeGoods()
# Search for stores near a ZIP code
for summary in client.stores.search(location="10001"):
print(summary.store_id, summary.city, summary.state, summary.zip_code, summary.street_address, summary.hours)
# List stores filtered by state using the State enum
for summary in client.stores.list(state=State.CT):
print(summary.store_id, summary.city, summary.zip_code, summary.phone, summary.plaza_name)
# Navigate from a summary to full store details
for s in client.stores.search(location="90210", limit=1):
detail = s.details()
print(detail.brand, detail.location_name, detail.current_status, detail.phone, detail.full_address)
for day, time in detail.hours.items():
print(day, time)
# Fetch a store directly by ID
store = client.stores.get(store_id="0515")
print(store.brand, store.location_name, store.full_address, store.phone, store.current_status)
Search for HomeGoods stores near a location. Accepts a location string (zip code, city, address) or latitude/longitude coordinates. Returns up to 25 nearby stores sorted by distance. Each store includes address, hours, and rank by proximity. Either location or latitude+longitude must be provided.
| Param | Type | Description |
|---|---|---|
| limit | integer | Maximum number of stores to return. |
| latitude | number | Latitude coordinate. Must be used with longitude. |
| location | string | Location to search near (e.g., '10001', 'Los Angeles, CA', '123 Main St, Chicago IL'). Either location or latitude+longitude must be provided. |
| longitude | number | Longitude coordinate. Must be used with latitude. |
{
"type": "object",
"fields": {
"stores": "array of store summary objects with store_id, city, state, zip_code, street_address, hours, rank, and optional plaza_name and services",
"latitude": "number, latitude of search center",
"location": "string, the search location used",
"longitude": "number, longitude of search center",
"total_results": "integer, number of stores returned"
},
"sample": {
"data": {
"stores": [
{
"city": "New York (Upper West)",
"rank": "1",
"hours": "Mon-Sun: 9:30AM-9:30PM",
"state": "NY",
"store_id": "0515",
"url_slug": "New-York-(Upper-West)-NY-10025",
"zip_code": "10025",
"detail_url": "/store-details/New-York-(Upper-West)-NY-10025/0515",
"street_address": "795 Columbus Ave"
}
],
"latitude": 40.7485672,
"location": "10001",
"longitude": -73.9940065,
"total_results": 3
},
"status": "success"
}
}About the HomeGoods API
Store Search and Discovery
The search_stores endpoint accepts either a location string (zip code, city, or street address) or a latitude/longitude coordinate pair and returns up to 25 nearby stores sorted by proximity. Each result includes store_id, street_address, city, state, zip_code, hours, rank, and — where applicable — plaza_name and a services array. The response also echoes back the resolved latitude, longitude, and location used as the search center, which is useful for map rendering.
Store Detail Lookup
Once you have a store_id from search_stores or list_stores, pass it to get_store_details to get the full store record. This endpoint returns brand, location_name, full_address, phone, a hours object keyed by day name (e.g. "Monday": "9:00 AM - 9:00 PM"), a services array, and current_status indicating whether the store is open or closed at query time.
Bulk Listing and Pagination
The list_stores endpoint returns all HomeGoods stores in the US, with optional filtering by two-letter state code (e.g. CA, TX). Results are paginated using offset and limit parameters. Each page response includes total_stores so you can calculate page counts, along with returned, offset, and state_filter. Each store record in the list includes url_slug, phone, and hours in addition to the standard address fields.
The HomeGoods API is a managed, monitored endpoint for homegoods.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when homegoods.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official homegoods.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Build a store-finder widget that resolves a user's zip code to nearby HomeGoods locations with hours and addresses.
- Generate a full state-by-state directory of HomeGoods stores using the
statefilter onlist_stores. - Check real-time
current_statusfor a specific store before routing a customer to it. - Display a map of nearby stores by using the
latitudeandlongitudereturned fromsearch_stores. - Index all HomeGoods store phone numbers and hours for a retail intelligence or competitor analysis dataset.
- Filter stores by available
servicesto find locations offering specific in-store amenities. - Sync a local database of store records by paginating through
list_storeswithoffsetandlimit.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does HomeGoods have an official public developer API for store locations?+
What does `get_store_details` return beyond what `search_stores` provides?+
get_store_details adds phone, brand, location_name, full_address, and current_status (open/closed at query time) to the data. The hours object is also structured as a day-keyed map, which is more convenient for display than the hours strings in search_stores results.Does the API cover HomeGoods locations outside the United States?+
list_stores state filter accepts US two-letter state codes only. You can fork this API on Parse and revise it to add coverage for other TJX-family banners or international markets if the underlying data becomes available.Does the API return product inventory, pricing, or online shopping data for HomeGoods?+
How fresh is the store hours and status data?+
current_status is derived from the published hours at query time.