Kroger APIkroger.com ↗
Access Kroger grocery store locations across the US. Get store directories by state, detailed city-level info, and proximity search by city, zip, or address.
What is the Kroger API?
The Kroger Store Locations API exposes 3 endpoints covering the full US store directory, returning fields like address, phone, hours, departments, and GPS coordinates for every Kroger location. Use get_all_stores to retrieve a state-by-state directory with city counts, get_stores_by_city for granular store details in a specific city, or search_stores to find nearby locations by zip code, city name, or street address.
curl -X GET 'https://api.parse.bot/scraper/91b3d669-c6ee-4818-bf5b-461d3d18cbe3/get_all_stores?state=Georgia' \ -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 kroger-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.
"""Walkthrough: Kroger Grocery Stores API — find stores by directory, city, or search."""
from parse_apis.kroger_grocery_stores_api import Kroger, CityNotFound
client = Kroger()
# Browse the full store directory, filtered to one state
directory = client.directories.get(state="Georgia")
print(f"Directory: {directory.total_states} states, {directory.total_cities} cities, {directory.total_stores} stores")
# Inspect state entries in the directory
for state_name, entry in directory.states.items():
print(f" {state_name}: {entry.city_count} cities")
first_city = entry.cities[0]
print(f" First city: {first_city.name} ({first_city.url_slug})")
# List stores in a specific city
for store in client.stores.list_by_city(city="acworth", state="ga", limit=3):
print(f"Store: {store.name} | {store.address}, {store.city}, {store.state} {store.zip_code}")
print(f" Phone: {store.phone} | Departments: {len(store.departments)}")
for h in store.hours:
print(f" Hours ({h.days}): {h.hours}")
# Search stores near a zip code
store = client.stores.search(query="30301", limit=1).first()
if store:
print(f"Nearest to 30301: {store.name} at ({store.latitude}, {store.longitude})")
# Typed error handling for an invalid city
try:
for s in client.stores.list_by_city(city="fakecityxyz", state="zz", limit=1):
print(s.name)
except CityNotFound as exc:
print(f"City not found: {exc.city}, {exc.state}")
print("Exercised: directories.get / stores.list_by_city / stores.search / CityNotFound")
Get the complete directory of all Kroger grocery stores grouped by state. Returns all states with their cities and store counts. The optional state filter narrows results to matching states (partial, case-insensitive). Returns a single Directory object, not a list.
| Param | Type | Description |
|---|---|---|
| state | string | Filter by state name (partial match, case-insensitive). Omitting returns all states. |
{
"type": "object",
"fields": {
"states": "object mapping state name to state entry with city_count and cities array",
"total_cities": "integer total number of cities across all states",
"total_states": "integer total number of states in the directory",
"total_stores": "integer total number of stores across all states"
}
}About the Kroger API
Store Directory by State
The get_all_stores endpoint returns the complete Kroger store directory organized as a mapping of state names to city arrays, each with a city-level store count. The response includes top-level aggregates: total_states, total_cities, and total_stores. Pass the optional state parameter with a partial name match (e.g., 'Georgia' or 'Ohio') to narrow results to a single state without fetching the full directory.
City-Level Store Details
get_stores_by_city accepts a required city string and two-letter state abbreviation and returns an array of store objects for that city. Each object includes location_id, name, brand, address, zip_code, phone, hours, departments, and latitude/longitude coordinates. The store_count field tells you how many locations exist in that city, and state_name gives the full state name alongside the abbreviation.
Proximity Search
search_stores accepts a freeform query — a city name, zip code, or street address — and returns stores sorted by proximity to that location. The same detailed store fields are included as in get_stores_by_city. Use page_size and page_offset to paginate through larger result sets; a pagination metadata object is included in the response, though it may be empty for small result sets.
Data Coverage
All three endpoints cover Kroger-branded grocery stores across the United States. The brand field in store objects reflects the specific banner (e.g., Kroger, Ralphs, Fred Meyer, King Soopers) since Kroger Co. operates under several regional names, though only Kroger-banner stores are indexed here.
The Kroger API is a managed, monitored endpoint for kroger.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when kroger.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 kroger.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 locator map using latitude/longitude coordinates from
get_stores_by_cityorsearch_stores. - Analyze Kroger's geographic footprint by state using
total_storesandtotal_citiesfromget_all_stores. - Identify which departments (pharmacy, deli, fuel center) are available at stores near a given zip code.
- Power a mobile app feature that finds the nearest Kroger by querying
search_storeswith a user's zip code. - Aggregate store hours data to determine which locations offer extended or 24-hour service.
- Compare store density across cities by combining city-level
store_countvalues from the state directory. - Validate or enrich an existing retail database with canonical Kroger
location_id, address, and phone fields.
| 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 Kroger have an official developer API for store locations?+
What store details does `get_stores_by_city` return beyond the address?+
phone, hours, a departments array (listing amenities like pharmacy or fuel center), latitude and longitude for mapping, a brand field indicating the banner name, and a unique location_id. The store_count in the response tells you how many stores are in that city.Does `search_stores` return results for all Kroger banner brands like Ralphs or Fred Meyer?+
brand field in the response reflects this scope. You can fork the API on Parse and revise it to target those banner-specific store directories and add the missing coverage.Can I retrieve product prices or inventory data through this API?+
How does pagination work in `search_stores`?+
page_size to control how many store results are returned per request and page_offset to step through pages. The response includes a pagination metadata object, though it may be empty when the result set is smaller than the page size. store_count always reflects the number of stores in the current response page.