Postmates APIpostmates.com ↗
Access Postmates restaurant feeds, menus, item details, and search via 7 endpoints. Get store ratings, hours, delivery info, and full menu structures by location.
What is the Postmates API?
The Postmates API covers 7 endpoints for browsing and querying restaurant and store data on postmates.com, from location-based feeds to individual menu item customizations. The get_restaurant_feed endpoint returns nearby stores with dining modes and filter options, while get_menu_item_details exposes per-item pricing in cents, descriptions, and customization groups — giving you the full data chain from discovery to item selection.
curl -X GET 'https://api.parse.bot/scraper/e8eb408e-fcea-460e-a5ef-7ae0b05d7e73/get_restaurant_feed?address=1600+Pennsylvania+Ave+NW%2C+Washington%2C+DC' \ -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 postmates-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: Postmates SDK — search stores, browse feed, get suggestions, and drill into details."""
from parse_apis.postmates_api import Postmates, Vertical, StoreNotFound
postmates = Postmates()
# Search for pizza restaurants near DC
for result in postmates.stores.search(query="pizza", vertical=Vertical.RESTAURANTS, limit=3):
print(result.uuid, result.type)
# Get autocomplete suggestions for a query
for suggestion in postmates.stores.suggestions(query="burger", limit=5):
print(suggestion.title, suggestion.type)
# Drill into full store details from search
result = postmates.stores.search(query="sushi", limit=1).first()
if result:
store = result.details()
print(store.title, store.rating.rating_value, store.rating.review_count)
print(store.location.address, store.location.city)
# Get a menu item's details
try:
item = store.item_details(
item_uuid="c68102b7-a2de-58af-8183-ed2a2ca0c3fb",
section_uuid="6e75b0fd-f3c6-58d8-b712-fa0362b1e17b"
)
print(item.title, item.price, item.has_customizations)
except StoreNotFound as exc:
print(f"Store or item not found: {exc}")
# Browse categories
categories = postmates.categorygroups.list()
print(categories.browse_home_feed, categories.vertical_search_home_results)
print("exercised: stores.search / stores.suggestions / details / item_details / categorygroups.list")
Returns a location-based feed of restaurants and stores available for delivery. Requires a delivery address to determine nearby options. Returns dining modes, sort/filter options, and a list of feed items including store carousels and regular store listings.
| Param | Type | Description |
|---|---|---|
| address | string | Delivery address to search near (e.g. '1600 Pennsylvania Ave NW, Washington, DC'). Defaults to Washington DC if not provided. |
{
"type": "object",
"fields": {
"feedItems": "array of restaurant/store feed entries including carousels and regular store listings",
"diningModes": "array of available dining modes (DELIVERY, PICKUP) with availability status",
"sortAndFilters": "array of sort and filter options with their values"
},
"sample": {
"data": {
"meta": {
"offset": 118,
"hasMore": true
},
"feedItems": [
{
"type": "REGULAR_CAROUSEL",
"uuid": "93491577-e3a6-4a56-aacc-f5edc65a7e68"
}
],
"diningModes": [
{
"mode": "DELIVERY",
"title": "Delivery",
"isSelected": true,
"isAvailable": true
}
],
"sortAndFilters": [
{
"type": "sort",
"uuid": "1c7cf7ef-730f-431f-9072-26bc39f7c021",
"label": "Sort"
}
]
},
"status": "success"
}
}About the Postmates API
Restaurant Discovery and Search
The get_restaurant_feed endpoint accepts a delivery address and returns a structured feed including store carousels, individual store listings, available diningModes (DELIVERY and PICKUP), and sortAndFilters options. The search_restaurants endpoint takes a query keyword and the same address parameter, and optionally a vertical filter (ALL, RESTAURANTS, SHOP, ALCOHOL) to narrow results by category. Each search result includes store ratings, delivery info, and image URLs. For typeahead behavior, get_search_suggestions returns both store-level suggestions (with UUIDs) and plain text keyword suggestions as the user types.
Menu and Item Data
Once you have a store UUID — from feed results or search — get_restaurant_details returns the full store record: title, location (address, city, latitude, longitude), hours by day range, a rating object with ratingValue and reviewCount, categories, and the complete catalogSectionsMap containing all menu sections and items. The get_restaurant_menu endpoint returns the same menu structure with explicit sectionsMap and catalogSectionsMap fields, mapping section UUIDs to arrays of subsection entries with their catalogItems.
Item-Level Details and Category Browsing
get_menu_item_details requires three UUIDs: item_uuid, store_uuid, and section_uuid, all obtainable from the menu response. It returns price in cents, title, itemDescription, and customizationsList — an array of customization groups with options. The optional subsection_uuid parameter, when provided, returns the item in full subsection context including any relevant modifiers. The get_categories endpoint requires no location input and returns top-level browsable categories organized under browseHomeFeed and verticalSearchHomeResults, mapped by vertical type.
The Postmates API is a managed, monitored endpoint for postmates.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when postmates.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 postmates.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 restaurant discovery app that shows nearby delivery and pickup options for a given address using
get_restaurant_feed. - Populate a food search interface with real-time autocomplete using
get_search_suggestionsstore and keyword results. - Display full menus with section structure and item prices from
get_restaurant_menufor any Postmates store. - Show modifier and customization options for menu items using
customizationsListfromget_menu_item_details. - Filter restaurant search results by vertical (RESTAURANTS, SHOP, ALCOHOL) via
search_restaurantsto build category-specific storefronts. - Aggregate store ratings and review counts across categories using
ratingValueandreviewCountfromget_restaurant_details. - Build a category browsing page using
get_categorieswithout requiring any location input.
| 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 Postmates have an official developer API?+
What does `get_restaurant_feed` return, and can I filter by dining mode?+
get_restaurant_feed returns feedItems (store carousels and individual store listings), diningModes (DELIVERY and PICKUP with availability status), and sortAndFilters options. The available filters are returned as part of the response itself, not as input parameters — you pass an address to establish location context, and the feed reflects what's available there.Does the API expose order placement or cart functionality?+
Are user reviews or written review text available from any endpoint?+
rating object returned by get_restaurant_details includes ratingValue and reviewCount at the store level. Individual written reviews and review text are not currently returned by any endpoint. You can fork this API on Parse and revise it to add a reviews endpoint if that data is needed.How do I get the UUIDs needed for `get_menu_item_details`?+
store_uuid comes from feed or search results. section_uuid is the top-level key in catalogSectionsMap from get_restaurant_menu. item_uuid comes from the catalogItems array within those sections. The optional subsection_uuid is the catalogSectionUUID field on each subsection entry in the same structure.