# Restaurant Dish Photo Matcher — Photos to Menu Items (`nomad-agent/dish-photo-matcher`) Actor
Match restaurant food & drink photos to the menu items they show, using AI vision. Feed it photo URLs — or a Google Maps place to scrape guest photos — plus your menu, and get {photoUrl, dishName} pairs back. Perfect for adding real photos to parsed menus. BYO Gemini key.
- **URL**: https://apify.com/nomad-agent/dish-photo-matcher.md
- **Developed by:** [Nomad.Dev](https://apify.com/nomad-agent) (community)
- **Categories:** AI, Travel
- **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet
## Pricing
from $2.00 / 1,000 photo matcheds
This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event
## What's an Apify Actor?
Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".
## How to integrate an Actor?
If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.
In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md):
```bash
npm install apify-client
```
In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md):
```bash
pip install apify-client
```
In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md):
````bash
# MacOS / Linux
curl -fsSL https://apify.com/install-cli.sh | bash
# Windows
irm https://apify.com/install-cli.ps1 | iex
```bash
In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md).
If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md).
For usage examples, see the [API](#api) section below.
For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).
# README
## Restaurant Dish Photo Matcher — Photos → Menu Items
Match restaurant **food & drink photos to the menu items they actually
show**, using AI vision. A menu without photos converts poorly; guest photos
without labels are just noise. This actor joins the two:
- **Input**: your menu (JSON array of items) + food/drink photos — either
direct `photoUrls`, or a Google Maps `placeUrl` whose "Food & drink"
guest photos are scraped automatically.
- **Output**: one record per photo — `{photoUrl, dishName, matched}`, with
`dishName` the exact menu item name or `null` when nothing matches.
Photos are matched in batches of 9 by visual appearance; hallucinated names
(not on your menu) are filtered to `null` automatically. Ported from the
production photo-matching pipeline of a dietary-restrictions travel app.
### Bring your own Gemini key
Matching runs on **your** Google AI Studio key
([get one free](https://aistudio.google.com/apikey)) — you control the AI
cost. Flash-Lite (default) matches a photo for a fraction of a cent.
### Input example
```json
{
"placeUrl": "https://www.google.com/maps/place/Katz's+Delicatessen,+205+E+Houston+St,+New+York",
"menuItems": [
{"name": "Pastrami on Rye", "category": "Sandwiches"},
{"name": "Matzo Ball Soup", "category": "Soups"}
],
"geminiApiKey": "AIza…"
}
````
### Notes
- `menuItems` accepts plain strings too: `["Pastrami on Rye", "Tiramisu"]`.
- **Place mode**: set the `outscraperApiKey` input
([free tier available](https://app.outscraper.com/profile)) — Google's
signed-out "limited view" hides the Maps photo gallery from automated
browsers, and Outscraper's API returns the full tagged photo set instead.
The browser fallback (with the Apify residential proxy) currently reaches
only the place's cover photo.
- Chain it: **Google Maps Menu Scraper** (or **AI Menu Parser**) extracts
the structured menu, then this actor attaches a real photo to each dish.
# Actor input Schema
## `menuItems` (type: `array`):
The restaurant's menu as a JSON array. Each item needs at least name; originalName, category and description improve match quality. Plain strings also work. Tip: the Google Maps Menu Scraper / AI Menu Parser actors produce compatible records.
## `photoUrls` (type: `array`):
Direct URLs of food/drink photos to match. Leave empty to scrape them from the Google Maps place below instead.
## `placeUrl` (type: `string`):
A Google Maps place URL or bare place ID (ChIJ…). Its "Food & drink" guest photos are scraped and matched. Ignored when photoUrls is set.
## `geminiApiKey` (type: `string`):
Your Google AI Studio API key — get a free one at aistudio.google.com/apikey. Matching runs on YOUR key, so you control the AI cost.
## `outscraperApiKey` (type: `string`):
API key from app.outscraper.com (free tier available). Google's signed-out "limited view" hides the Maps photo gallery from browsers, so this is the reliable way to fetch a place's tagged photos. Without it, the actor falls back to browser scraping, which currently reaches only the cover photo.
## `geminiModel` (type: `string`):
Model used to match photos to menu items.
## `maxPhotos` (type: `integer`):
Cap on how many photos are matched (photos are processed in batches of 9).
## `proxyConfiguration` (type: `object`):
Proxy used to open Google Maps (only in place mode). Google rate-limits datacenter IPs, so the Apify residential proxy is recommended.
## Actor input object example
```json
{
"menuItems": [
{
"name": "Margherita Pizza",
"category": "Pizza",
"description": "Tomato, mozzarella and basil"
},
{
"name": "Tiramisu",
"category": "Dessert"
}
],
"geminiModel": "gemini-3.1-flash-lite",
"maxPhotos": 27,
"proxyConfiguration": {
"useApifyProxy": true,
"apifyProxyGroups": [
"RESIDENTIAL"
]
}
}
```
# API
You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.
## JavaScript example
```javascript
import { ApifyClient } from 'apify-client';
// Initialize the ApifyClient with your Apify API token
// Replace the '' with your token
const client = new ApifyClient({
token: '',
});
// Prepare Actor input
const input = {
"menuItems": [
{
"name": "Margherita Pizza",
"category": "Pizza",
"description": "Tomato, mozzarella and basil"
},
{
"name": "Tiramisu",
"category": "Dessert"
}
],
"proxyConfiguration": {
"useApifyProxy": true,
"apifyProxyGroups": [
"RESIDENTIAL"
]
}
};
// Run the Actor and wait for it to finish
const run = await client.actor("nomad-agent/dish-photo-matcher").call(input);
// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
console.dir(item);
});
// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs
```
## Python example
```python
from apify_client import ApifyClient
# Initialize the ApifyClient with your Apify API token
# Replace '' with your token.
client = ApifyClient("")
# Prepare the Actor input
run_input = {
"menuItems": [
{
"name": "Margherita Pizza",
"category": "Pizza",
"description": "Tomato, mozzarella and basil",
},
{
"name": "Tiramisu",
"category": "Dessert",
},
],
"proxyConfiguration": {
"useApifyProxy": True,
"apifyProxyGroups": ["RESIDENTIAL"],
},
}
# Run the Actor and wait for it to finish
run = client.actor("nomad-agent/dish-photo-matcher").call(run_input=run_input)
# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
print(item)
# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start
```
## CLI example
```bash
echo '{
"menuItems": [
{
"name": "Margherita Pizza",
"category": "Pizza",
"description": "Tomato, mozzarella and basil"
},
{
"name": "Tiramisu",
"category": "Dessert"
}
],
"proxyConfiguration": {
"useApifyProxy": true,
"apifyProxyGroups": [
"RESIDENTIAL"
]
}
}' |
apify call nomad-agent/dish-photo-matcher --silent --output-dataset
```
## MCP server setup
```json
{
"mcpServers": {
"apify": {
"command": "npx",
"args": [
"mcp-remote",
"https://mcp.apify.com/?tools=nomad-agent/dish-photo-matcher",
"--header",
"Authorization: Bearer "
]
}
}
}
```
## OpenAPI specification
```json
{
"openapi": "3.0.1",
"info": {
"title": "Restaurant Dish Photo Matcher — Photos to Menu Items",
"description": "Match restaurant food & drink photos to the menu items they show, using AI vision. Feed it photo URLs — or a Google Maps place to scrape guest photos — plus your menu, and get {photoUrl, dishName} pairs back. Perfect for adding real photos to parsed menus. BYO Gemini key.",
"version": "0.1",
"x-build-id": "eWnGqZjqPYFfRjIUo"
},
"servers": [
{
"url": "https://api.apify.com/v2"
}
],
"paths": {
"/acts/nomad-agent~dish-photo-matcher/run-sync-get-dataset-items": {
"post": {
"operationId": "run-sync-get-dataset-items-nomad-agent-dish-photo-matcher",
"x-openai-isConsequential": false,
"summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
"tags": [
"Run Actor"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inputSchema"
}
}
}
},
"parameters": [
{
"name": "token",
"in": "query",
"required": true,
"schema": {
"type": "string"
},
"description": "Enter your Apify token here"
}
],
"responses": {
"200": {
"description": "OK"
}
}
}
},
"/acts/nomad-agent~dish-photo-matcher/runs": {
"post": {
"operationId": "runs-sync-nomad-agent-dish-photo-matcher",
"x-openai-isConsequential": false,
"summary": "Executes an Actor and returns information about the initiated run in response.",
"tags": [
"Run Actor"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inputSchema"
}
}
}
},
"parameters": [
{
"name": "token",
"in": "query",
"required": true,
"schema": {
"type": "string"
},
"description": "Enter your Apify token here"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/runsResponseSchema"
}
}
}
}
}
}
},
"/acts/nomad-agent~dish-photo-matcher/run-sync": {
"post": {
"operationId": "run-sync-nomad-agent-dish-photo-matcher",
"x-openai-isConsequential": false,
"summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
"tags": [
"Run Actor"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inputSchema"
}
}
}
},
"parameters": [
{
"name": "token",
"in": "query",
"required": true,
"schema": {
"type": "string"
},
"description": "Enter your Apify token here"
}
],
"responses": {
"200": {
"description": "OK"
}
}
}
}
},
"components": {
"schemas": {
"inputSchema": {
"type": "object",
"required": [
"menuItems",
"geminiApiKey"
],
"properties": {
"menuItems": {
"title": "Menu items",
"type": "array",
"description": "The restaurant's menu as a JSON array. Each item needs at least name; originalName, category and description improve match quality. Plain strings also work. Tip: the Google Maps Menu Scraper / AI Menu Parser actors produce compatible records."
},
"photoUrls": {
"title": "Food/drink photo URLs",
"type": "array",
"description": "Direct URLs of food/drink photos to match. Leave empty to scrape them from the Google Maps place below instead.",
"items": {
"type": "string"
}
},
"placeUrl": {
"title": "Google Maps place (alternative to photo URLs)",
"type": "string",
"description": "A Google Maps place URL or bare place ID (ChIJ…). Its \"Food & drink\" guest photos are scraped and matched. Ignored when photoUrls is set."
},
"geminiApiKey": {
"title": "Gemini API key (bring your own)",
"type": "string",
"description": "Your Google AI Studio API key — get a free one at aistudio.google.com/apikey. Matching runs on YOUR key, so you control the AI cost."
},
"outscraperApiKey": {
"title": "Outscraper API key (recommended)",
"type": "string",
"description": "API key from app.outscraper.com (free tier available). Google's signed-out \"limited view\" hides the Maps photo gallery from browsers, so this is the reliable way to fetch a place's tagged photos. Without it, the actor falls back to browser scraping, which currently reaches only the cover photo."
},
"geminiModel": {
"title": "Gemini model",
"enum": [
"gemini-3.1-flash-lite",
"gemini-3.5-flash",
"gemini-3.1-pro-preview"
],
"type": "string",
"description": "Model used to match photos to menu items.",
"default": "gemini-3.1-flash-lite"
},
"maxPhotos": {
"title": "Max photos",
"minimum": 1,
"maximum": 100,
"type": "integer",
"description": "Cap on how many photos are matched (photos are processed in batches of 9).",
"default": 27
},
"proxyConfiguration": {
"title": "Proxy configuration",
"type": "object",
"description": "Proxy used to open Google Maps (only in place mode). Google rate-limits datacenter IPs, so the Apify residential proxy is recommended."
}
}
},
"runsResponseSchema": {
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"actId": {
"type": "string"
},
"userId": {
"type": "string"
},
"startedAt": {
"type": "string",
"format": "date-time",
"example": "2025-01-08T00:00:00.000Z"
},
"finishedAt": {
"type": "string",
"format": "date-time",
"example": "2025-01-08T00:00:00.000Z"
},
"status": {
"type": "string",
"example": "READY"
},
"meta": {
"type": "object",
"properties": {
"origin": {
"type": "string",
"example": "API"
},
"userAgent": {
"type": "string"
}
}
},
"stats": {
"type": "object",
"properties": {
"inputBodyLen": {
"type": "integer",
"example": 2000
},
"rebootCount": {
"type": "integer",
"example": 0
},
"restartCount": {
"type": "integer",
"example": 0
},
"resurrectCount": {
"type": "integer",
"example": 0
},
"computeUnits": {
"type": "integer",
"example": 0
}
}
},
"options": {
"type": "object",
"properties": {
"build": {
"type": "string",
"example": "latest"
},
"timeoutSecs": {
"type": "integer",
"example": 300
},
"memoryMbytes": {
"type": "integer",
"example": 1024
},
"diskMbytes": {
"type": "integer",
"example": 2048
}
}
},
"buildId": {
"type": "string"
},
"defaultKeyValueStoreId": {
"type": "string"
},
"defaultDatasetId": {
"type": "string"
},
"defaultRequestQueueId": {
"type": "string"
},
"buildNumber": {
"type": "string",
"example": "1.0.0"
},
"containerUrl": {
"type": "string"
},
"usage": {
"type": "object",
"properties": {
"ACTOR_COMPUTE_UNITS": {
"type": "integer",
"example": 0
},
"DATASET_READS": {
"type": "integer",
"example": 0
},
"DATASET_WRITES": {
"type": "integer",
"example": 0
},
"KEY_VALUE_STORE_READS": {
"type": "integer",
"example": 0
},
"KEY_VALUE_STORE_WRITES": {
"type": "integer",
"example": 1
},
"KEY_VALUE_STORE_LISTS": {
"type": "integer",
"example": 0
},
"REQUEST_QUEUE_READS": {
"type": "integer",
"example": 0
},
"REQUEST_QUEUE_WRITES": {
"type": "integer",
"example": 0
},
"DATA_TRANSFER_INTERNAL_GBYTES": {
"type": "integer",
"example": 0
},
"DATA_TRANSFER_EXTERNAL_GBYTES": {
"type": "integer",
"example": 0
},
"PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
"type": "integer",
"example": 0
},
"PROXY_SERPS": {
"type": "integer",
"example": 0
}
}
},
"usageTotalUsd": {
"type": "number",
"example": 0.00005
},
"usageUsd": {
"type": "object",
"properties": {
"ACTOR_COMPUTE_UNITS": {
"type": "integer",
"example": 0
},
"DATASET_READS": {
"type": "integer",
"example": 0
},
"DATASET_WRITES": {
"type": "integer",
"example": 0
},
"KEY_VALUE_STORE_READS": {
"type": "integer",
"example": 0
},
"KEY_VALUE_STORE_WRITES": {
"type": "number",
"example": 0.00005
},
"KEY_VALUE_STORE_LISTS": {
"type": "integer",
"example": 0
},
"REQUEST_QUEUE_READS": {
"type": "integer",
"example": 0
},
"REQUEST_QUEUE_WRITES": {
"type": "integer",
"example": 0
},
"DATA_TRANSFER_INTERNAL_GBYTES": {
"type": "integer",
"example": 0
},
"DATA_TRANSFER_EXTERNAL_GBYTES": {
"type": "integer",
"example": 0
},
"PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
"type": "integer",
"example": 0
},
"PROXY_SERPS": {
"type": "integer",
"example": 0
}
}
}
}
}
}
}
}
}
}
```