Skip to content

Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. 🔥

feat: add `menu` scrape format (engine client + 9 SDKs, menuBeta-gated) (#3831)

Kris Oei6840ee516f60
diff --git a/apps/api/.env.example b/apps/api/.env.example
index c4b8a0818..2da496768 100644
--- a/apps/api/.env.example
+++ b/apps/api/.env.example
@@ -77,6 +77,7 @@ FIRE_ENGINE_BETA_URL=
# `product` format returns a warning and no product (same pattern as the
# audio/video formats and AVGRAB_SERVICE_URL).
PRODUCT_EXTRACTION_SERVICE_URL=
+MENU_EXTRACTION_SERVICE_URL=
# Proxy Settings for Playwright (Alternative you can use a proxy service like oxylabs, which rotates IPs for you on every request)
PROXY_SERVER=
diff --git a/apps/api/src/__tests__/snips/lib.ts b/apps/api/src/__tests__/snips/lib.ts
index 78f2c2ca9..2755956fa 100644
--- a/apps/api/src/__tests__/snips/lib.ts
+++ b/apps/api/src/__tests__/snips/lib.ts
@@ -27,6 +27,7 @@ export const HAS_FIRE_ENGINE = !!config.FIRE_ENGINE_BETA_URL;
export const HAS_PLAYWRIGHT = !!config.PLAYWRIGHT_MICROSERVICE_URL;
export const HAS_PROXY = !!config.PROXY_SERVER;
export const HAS_PRODUCT_SERVICE = !!config.PRODUCT_EXTRACTION_SERVICE_URL;
+export const HAS_MENU_SERVICE = !!config.MENU_EXTRACTION_SERVICE_URL;
export const HAS_SEARCH = TEST_PRODUCTION || !!config.SEARXNG_ENDPOINT;
diff --git a/apps/api/src/__tests__/snips/v1/menu.test.ts b/apps/api/src/__tests__/snips/v1/menu.test.ts
new file mode 100644
index 000000000..e07f77725
--- /dev/null
+++ b/apps/api/src/__tests__/snips/v1/menu.test.ts
@@ -0,0 +1,52 @@
+import {
+ ALLOW_TEST_SUITE_WEBSITE,
+ describeIf,
+ TEST_SUITE_WEBSITE,
+} from "../lib";
+import { scrape, scrapeTimeout, idmux, Identity } from "./lib";
+
+let identity: Identity;
+
+beforeAll(async () => {
+ identity = await idmux({
+ name: "menu-v1",
+ concurrency: 100,
+ credits: 1000000,
+ });
+}, 10000 + scrapeTimeout);
+
+// The `menu` scrape format is registered for both v1 and v2. The v2 suite covers
+// the positive extraction paths; here we only need to prove the additive-only
+// contract on v1: a scrape that does NOT request the `menu` format is
+// byte-identical in shape to a pre-feature v1 scrape (no `menu`, no spurious
+// `warning`, markdown + metadata intact). The menu transformer is shared across
+// v1/v2, so this guards the v1 format gate specifically.
+describeIf(ALLOW_TEST_SUITE_WEBSITE)(
+ "Menu scrape format (v1 back-compat)",
+ () => {
+ const base = TEST_SUITE_WEBSITE;
+ const menuUrl = `${base}/product`;
+
+ it.concurrent(
+ "does not populate menu when the menu format is not requested (v1)",
+ async () => {
+ const response = await scrape(
+ {
+ url: menuUrl,
+ formats: ["markdown"],
+ },
+ identity,
+ );
+
+ expect(response.menu).toBeUndefined();
+ expect(response.warning).toBeUndefined();
+ expect(response.markdown).toBeDefined();
+ expect(typeof response.markdown).toBe("string");
+ expect(response.markdown?.length).toBeGreaterThan(0);
+ expect(response.metadata).toBeDefined();
+ expect(response.metadata.statusCode).toBe(200);
+ },
+ scrapeTimeout,
+ );
+ },
+);
diff --git a/apps/api/src/__tests__/snips/v2/menu.test.ts b/apps/api/src/__tests__/snips/v2/menu.test.ts
new file mode 100644
index 000000000..383248e44
--- /dev/null
+++ b/apps/api/src/__tests__/snips/v2/menu.test.ts
@@ -0,0 +1,116 @@
+import {
+ ALLOW_TEST_SUITE_WEBSITE,
+ describeIf,
+ HAS_MENU_SERVICE,
+ TEST_SUITE_WEBSITE,
+} from "../lib";
+import { scrape, scrapeTimeout, idmux, Identity } from "./lib";
+
+let identity: Identity;
+
+beforeAll(async () => {
+ identity = await idmux({
+ name: "menu",
+ concurrency: 100,
+ credits: 1000000,
+ });
+}, 10000 + scrapeTimeout);
+
+// The `menu` scrape format extracts a structured restaurant menu from a page's
+// HTML. The extraction itself runs in the menu-search Rust service, called over
+// HTTP when MENU_EXTRACTION_SERVICE_URL is set (the product → PRODUCT_EXTRACTION_
+// SERVICE_URL pattern). These tests target a representative real restaurant menu
+// page for the positive path, and the static test-site non-menu pages
+// (`/about`, `/product`) for the negative / absence paths. Because the format
+// requires the external extractor, we gate on HAS_MENU_SERVICE so the suite only
+// runs where the service is configured (mirroring how the product snips are
+// gated on HAS_PRODUCT_SERVICE); and we also gate on ALLOW_TEST_SUITE_WEBSITE
+// because the negative / absence cases fetch the local test-site.
+describeIf(ALLOW_TEST_SUITE_WEBSITE && HAS_MENU_SERVICE)(
+ "Menu scrape format",
+ () => {
+ const base = TEST_SUITE_WEBSITE;
+ // A representative restaurant menu page (Toast online ordering) for the live
+ // extraction path. The page embeds a structured menu the service can parse.
+ const menuUrl =
+ "https://order.toasttab.com/online/the-coffee-shop-123-main-st";
+ const nonMenuUrl = `${base}/about`;
+ const productUrl = `${base}/product`;
+
+ it.concurrent(
+ "extracts a structured menu from a restaurant menu page",
+ async () => {
+ const response = await scrape(
+ {
+ url: menuUrl,
+ formats: [{ type: "menu" }],
+ },
+ identity,
+ );
+
+ expect(response.menu).toBeDefined();
+ // Canonical shape: a merchant profile plus an ordered list of sections,
+ // each holding items.
+ expect(response.menu?.isMenu).toBe(true);
+ expect(response.menu?.merchant).toBeDefined();
+ expect(typeof response.menu?.merchant?.name).toBe("string");
+ expect(Array.isArray(response.menu?.sections)).toBe(true);
+ expect(response.menu?.sections?.length).toBeGreaterThan(0);
+ const section = response.menu?.sections?.[0];
+ expect(section).toBeDefined();
+ expect(typeof section?.name).toBe("string");
+ expect(Array.isArray(section?.items)).toBe(true);
+ },
+ scrapeTimeout,
+ );
+
+ it.concurrent(
+ "sets a no-menu warning for a non-menu page",
+ async () => {
+ const response = await scrape(
+ {
+ url: nonMenuUrl,
+ formats: [{ type: "menu" }],
+ },
+ identity,
+ );
+
+ expect(response.menu).toBeUndefined();
+ expect(response.warning).toBeDefined();
+ expect(response.warning).toContain("No menu found");
+ },
+ scrapeTimeout,
+ );
+
+ it.concurrent(
+ "does not populate menu when the menu format is not requested",
+ async () => {
+ const response = await scrape(
+ {
+ url: productUrl,
+ formats: ["markdown"],
+ },
+ identity,
+ );
+
+ // Additive-only contract: a scrape that does not request the `menu`
+ // format must be byte-identical in shape to a pre-feature scrape.
+ // No `menu` field...
+ expect(response.menu).toBeUndefined();
+ // ...and no spurious `warning` (the no-menu warning is only emitted when
+ // the format is actually requested).
+ expect(response.warning).toBeUndefined();
+ // ...while the rest of the document is present and unchanged.
+ expect(response.markdown).toBeDefined();
+ expect(typeof response.markdown).toBe("string");
+ expect(response.markdown?.length).toBeGreaterThan(0);
+ expect(response.metadata).toBeDefined();
+ expect(response.metadata.sourceURL ?? response.metadata.url).toBe(
+ productUrl,
+ );
+ expect(response.metadata.statusCode).toBe(200);
+ },
+ scrapeTimeout,
+ );
+ },
+);
diff --git a/apps/api/src/config.ts b/apps/api/src/config.ts
index 86eb7346a..88105b218 100644
--- a/apps/api/src/config.ts
+++ b/apps/api/src/config.ts
@@ -330,6 +330,9 @@ const configSchema = z.object({
// Product extraction (product-search Rust service)
PRODUCT_EXTRACTION_SERVICE_URL: z.string().optional(),
+ // Menu extraction (menu-search Rust service)
+ MENU_EXTRACTION_SERVICE_URL: z.string().optional(),
+
// PII Redaction (fire-privacy)
FIRE_PRIVACY_URL: z.string().optional(),
FIRE_PRIVACY_TIMEOUT_MS: z.coerce.number().int().positive().default(5000),
diff --git a/apps/api/src/controllers/v1/types.ts b/apps/api/src/controllers/v1/types.ts
index 8ae4f31ad..3d3165600 100644
--- a/apps/api/src/controllers/v1/types.ts
+++ b/apps/api/src/controllers/v1/types.ts
@@ -18,6 +18,7 @@ import { includesFormat } from "../../lib/format-utils";
import { webhookSchema } from "../../services/webhook/schema";
import { BrandingProfile } from "../../types/branding";
import { ProductProfile } from "../../types/product";
+import { MenuProfile } from "../../types/menu";
type Format =
| "markdown"
@@ -31,7 +32,8 @@ type Format =
| "summary"
| "changeTracking"
| "branding"
- | "product";
+ | "product"
+ | "menu";
export const url = z.preprocess(
x => {
@@ -432,6 +434,7 @@ const baseScrapeOptions = z.strictObject({
"changeTracking",
"branding",
"product",
+ "menu",
])
.array()
.optional()
@@ -996,6 +999,7 @@ export type Document = {
summary?: string;
branding?: BrandingProfile;
product?: ProductProfile;
+ menu?: MenuProfile;
warning?: string;
actions?: {
screenshots?: string[];
@@ -1563,6 +1567,7 @@ export const searchRequestSchema = z
"extract",
"json",
"product",
+ "menu",
]),
)
.prefault([]),
diff --git a/apps/api/src/controllers/v2/types.ts b/apps/api/src/controllers/v2/types.ts
index a398e4fc7..261e3f33c 100644
--- a/apps/api/src/controllers/v2/types.ts
+++ b/apps/api/src/controllers/v2/types.ts
@@ -27,6 +27,7 @@ import {
} from "../../services/webhook/schema";
import { BrandingProfile } from "../../types/branding";
import { ProductProfile } from "../../types/product";
+import { MenuProfile } from "../../types/menu";
// Base URL schema with common validation logic
export const URL = z.preprocess(
@@ -460,6 +461,7 @@ export type FormatObject =
| QueryFormatWithOptions
| { type: "branding" }
| { type: "product" }
+ | { type: "menu" }
| { type: "audio" }
| { type: "video" };
@@ -632,6 +634,7 @@ const baseScrapeOptions = z.strictObject({
attributesFormatWithOptions,
z.strictObject({ type: z.literal("branding") }),
z.strictObject({ type: z.literal("product") }),
+ z.strictObject({ type: z.literal("menu") }),
questionFormatWithOptions,
highlightsFormatWithOptions,
queryFormatWithOptions,
@@ -1208,6 +1211,7 @@ export type Document = {
highlights?: string;
branding?: BrandingProfile;
product?: ProductProfile;
+ menu?: MenuProfile;
warning?: string;
attributes?: {
selector: string;
@@ -1531,6 +1535,7 @@ export type TeamFlags = {
maxBrowserSessions?: number;
researchBeta?: boolean;
highlightsBeta?: boolean;
+ menuBeta?: boolean;
} | null;
interface RequestWithMaybeACUC<
@@ -1779,6 +1784,8 @@ export function fromV1ScrapeOptions(
return { type: "branding" as const };
} else if (x === "product") {
return { type: "product" as const };
+ } else if (x === "menu") {
+ return { type: "menu" as const };
} else {
return x;
}
@@ -1940,6 +1947,7 @@ export const searchRequestSchema = z
z.strictObject({ type: z.literal("images") }),
z.strictObject({ type: z.literal("summary") }),
z.strictObject({ type: z.literal("product") }),
+ z.strictObject({ type: z.literal("menu") }),
jsonFormatWithOptions,
questionFormatWithOptions,
highlightsFormatWithOptions,
diff --git a/apps/api/src/scraper/scrapeURL/transformers/__tests__/menu.test.ts b/apps/api/src/scraper/scrapeURL/transformers/__tests__/menu.test.ts
new file mode 100644
index 000000000..857c7842d
--- /dev/null
+++ b/apps/api/src/scraper/scrapeURL/transformers/__tests__/menu.test.ts
@@ -0,0 +1,158 @@
+import { fetchMenu } from "../menu";
+import { config } from "../../../../config";
+
+describe("fetchMenu", () => {
+ const originalFetch = global.fetch;
+ const originalServiceUrl = config.MENU_EXTRACTION_SERVICE_URL;
+
+ afterEach(() => {
+ global.fetch = originalFetch;
+ config.MENU_EXTRACTION_SERVICE_URL = originalServiceUrl;
+ vi.clearAllMocks();
+ });
+
+ function baseMeta(
+ formats: any[] = [{ type: "menu" }],
+ teamFlags: any = { menuBeta: true },
+ ) {
+ return {
+ url: "https://shop.test/menu",
+ rewrittenUrl: "https://shop.test/menu",
+ options: { formats },
+ internalOptions: { teamFlags },
+ logger: { warn: vi.fn(), info: vi.fn(), debug: vi.fn(), error: vi.fn() },
+ } as any;
+ }
+
+ it("skips silently when the team lacks the menuBeta flag", async () => {
+ config.MENU_EXTRACTION_SERVICE_URL = "https://menu.internal";
+ const fetchSpy = vi.fn();
+ global.fetch = fetchSpy as any;
+ const document: any = {
+ rawHtml: "<html></html>",
+ metadata: { url: "https://shop.test/menu" },
+ };
+
+ // menuBeta not enabled -> no engine call, no menu, no warning (fail closed)
+ const out = await fetchMenu(baseMeta([{ type: "menu" }], {}), document);
+
+ expect(fetchSpy).not.toHaveBeenCalled();
+ expect(out.menu).toBeUndefined();
+ expect(out.warning).toBeUndefined();
+ });
+
+ it("warns and yields no menu when the service is not configured", async () => {
+ config.MENU_EXTRACTION_SERVICE_URL = undefined;
+ const fetchSpy = vi.fn();
+ global.fetch = fetchSpy as any;
+ const document: any = {
+ rawHtml: "<html></html>",
+ metadata: { url: "https://shop.test/menu" },
+ };
+
+ const out = await fetchMenu(baseMeta(), document);
+
+ expect(fetchSpy).not.toHaveBeenCalled();
+ expect(out.menu).toBeUndefined();
+ expect(out.warning).toMatch(/not available/i);
+ });
+
+ it("posts rawHtml to the service and sets document.menu", async () => {
+ config.MENU_EXTRACTION_SERVICE_URL = "https://menu.internal";
+ const menu = {
+ isMenu: true,
+ confidence: 0.9,
+ merchant: { name: "Test Diner" },
+ sections: [],
+ sourceUrl: "https://shop.test/menu",
+ };
+ const fetchSpy = vi.fn(async (_url: string, _init?: RequestInit) => ({
+ ok: true,
+ json: async () => ({ menu }),
+ }));
+ global.fetch = fetchSpy as any;
+ const document: any = {
+ rawHtml: "<html>jsonld</html>",
+ metadata: { url: "https://shop.test/menu", title: "Test Diner Menu" },
+ };
+
+ const out = await fetchMenu(baseMeta(), document);
+
+ expect(out.menu).toEqual(menu);
+ const [calledUrl, init] = fetchSpy.mock.calls[0];
+ expect(calledUrl).toBe("https://menu.internal/v1/scrape-menu");
+ expect(init!.method).toBe("POST");
+ expect(JSON.parse(init!.body as string)).toEqual({
+ html: "<html>jsonld</html>",
+ url: "https://shop.test/menu",
+ title: "Test Diner Menu",
+ });
+ });
+
+ it("warns (no menu) when the service reports no menu", async () => {
+ config.MENU_EXTRACTION_SERVICE_URL = "https://menu.internal";
+ global.fetch = vi.fn(async () => ({
+ ok: true,
+ json: async () => ({ menu: null }),
+ })) as any;
+ const document: any = {
+ rawHtml: "<p>about</p>",
+ metadata: { url: "https://shop.test/about" },
+ };
+
+ const out = await fetchMenu(baseMeta(), document);
+
+ expect(out.menu).toBeUndefined();
+ expect(out.warning).toMatch(/no menu found/i);
+ });
+
+ it("throws when the service returns a non-JSON 200 response", async () => {
+ config.MENU_EXTRACTION_SERVICE_URL = "https://menu.internal";
+ global.fetch = vi.fn(async () => ({
+ ok: true,
+ json: async () => {
+ throw new SyntaxError("Unexpected token < in JSON");
+ },
+ })) as any;
+ const document: any = {
+ rawHtml: "<html></html>",
+ metadata: { url: "https://shop.test/menu" },
+ };
+
+ await expect(fetchMenu(baseMeta(), document)).rejects.toThrow(
+ /Menu extraction failed/i,
+ );
+ expect(document.menu).toBeUndefined();
+ expect(document.warning).toBeUndefined();
+ });
+
+ it("throws when the service 200 response omits the menu key", async () => {
+ config.MENU_EXTRACTION_SERVICE_URL = "https://menu.internal";
+ global.fetch = vi.fn(async () => ({
+ ok: true,
+ json: async () => ({ unexpected: "shape" }),
+ })) as any;
+ const document: any = {
+ rawHtml: "<html></html>",
+ metadata: { url: "https://shop.test/menu" },
+ };
+
+ await expect(fetchMenu(baseMeta(), document)).rejects.toThrow(
+ /unexpected response/i,
+ );
+ expect(document.menu).toBeUndefined();
+ expect(document.warning).toBeUndefined();
+ });
+
+ it("early-returns when the menu format isn't requested", async () => {
+ const fetchSpy = vi.fn();
+ global.fetch = fetchSpy as any;
+ const document: any = { rawHtml: "<html></html>", metadata: {} };
+
+ const out = await fetchMenu(baseMeta([{ type: "markdown" }]), document);
+
+ expect(fetchSpy).not.toHaveBeenCalled();
+ expect(out.menu).toBeUndefined();
+ expect(out.warning).toBeUndefined();
+ });
+});
diff --git a/apps/api/src/scraper/scrapeURL/transformers/index.ts b/apps/api/src/scraper/scrapeURL/transformers/index.ts
index cb0a96017..fb0146123 100644
--- a/apps/api/src/scraper/scrapeURL/transformers/index.ts
+++ b/apps/api/src/scraper/scrapeURL/transformers/index.ts
@@ -19,6 +19,7 @@ import { performAttributes } from "./performAttributes";
import { deriveDiff } from "./diff";
import { fetchAudio } from "./audio";
import { fetchProduct } from "./product";
+import { fetchMenu } from "./menu";
import { fetchVideo } from "./video";
import { performRedactPII } from "./redactPII";
import { useIndex, useSearchIndex } from "../../../services/index";
@@ -336,6 +337,7 @@ function coerceFieldsToFormats(meta: Meta, document: Document): Document {
const hasSummary = hasFormatOfType(meta.options.formats, "summary");
const hasBranding = hasFormatOfType(meta.options.formats, "branding");
const hasProduct = hasFormatOfType(meta.options.formats, "product");
+ const hasMenu = hasFormatOfType(meta.options.formats, "menu");
const hasQuestionFormat = hasFormatOfType(meta.options.formats, "question");
const hasHighlightsFormat = hasFormatOfType(
meta.options.formats,
@@ -497,6 +499,13 @@ function coerceFieldsToFormats(meta: Meta, document: Document): Document {
delete document.product;
}
+ if (!hasMenu && document.menu !== undefined) {
+ meta.logger.warn(
+ "Removed menu from Document because it wasn't in formats -- this indicates the engine returned unexpected data.",
+ );
+ delete document.menu;
+ }
+
const hasAudio = hasFormatOfType(meta.options.formats, "audio");
if (!hasAudio && document.audio !== undefined) {
delete document.audio;
@@ -587,6 +596,7 @@ const transformerStack: Transformer[] = [
deriveBrandingFromActions,
deriveMetadataFromRawHTML,
fetchProduct,
+ fetchMenu,
...(useIndex ? [sendDocumentToIndex] : []),
...(useSearchIndex ? [sendDocumentToSearchIndex] : []), // Add to search index for real-time search
performLLMExtract,
diff --git a/apps/api/src/scraper/scrapeURL/transformers/menu.ts b/apps/api/src/scraper/scrapeURL/transformers/menu.ts
new file mode 100644
index 000000000..a5e470612
--- /dev/null
+++ b/apps/api/src/scraper/scrapeURL/transformers/menu.ts
@@ -0,0 +1,90 @@
+import { Meta } from "..";
+import { Document } from "../../../controllers/v2/types";
+import { config } from "../../../config";
+import { hasFormatOfType } from "../../../lib/format-utils";
+
+export async function fetchMenu(
+ meta: Meta,
+ document: Document,
+): Promise<Document> {
+ if (!hasFormatOfType(meta.options.formats, "menu")) {
+ return document;
+ }
+
+ // Beta gate: during beta the menu format is limited to teams with the menuBeta
+ // flag. Fail closed and silent (mirrors highlightsBeta) -- a team without the
+ // flag gets no menu field, no error, and no engine call.
+ if (meta.internalOptions?.teamFlags?.menuBeta !== true) {
+ meta.logger.info("menu format requested without menuBeta flag; skipping");
+ return document;
+ }
+
+ if (!config.MENU_EXTRACTION_SERVICE_URL) {
+ meta.logger.warn("MENU_EXTRACTION_SERVICE_URL is not configured");
+ document.warning =
+ "Menu format is not available (service not configured)." +
+ (document.warning ? " " + document.warning : "");
+ return document;
+ }
+
+ if (document.rawHtml === undefined) {
+ throw new Error(
+ "rawHtml is undefined -- fetchMenu must run after rawHtml is available",
+ );
+ }
+
+ const url =
+ document.metadata.url ??
+ document.metadata.sourceURL ??
+ meta.rewrittenUrl ??
+ meta.url;
+
+ const response = await fetch(
+ `${config.MENU_EXTRACTION_SERVICE_URL}/v1/scrape-menu`,
+ {
+ method: "POST",
+ headers: { "Content-Type": "application/json" },
+ body: JSON.stringify({
+ html: document.rawHtml,
+ url,
+ title: document.metadata.title ?? undefined,
+ }),
+ },
+ );
+
+ if (!response.ok) {
+ const error = await response
+ .json()
+ .catch(() => ({ detail: "Unknown error" }));
+ throw new Error(`Menu extraction failed: ${error.detail}`);
+ }
+
+ let data: any;
+ try {
+ data = await response.json();
+ } catch {
+ throw new Error(
+ "Menu extraction failed: service returned a non-JSON response",
+ );
+ }
+
+ // The service contract is a 200 with a body of `{ menu: Menu | null }`.
+ // A body that isn't an object, or is missing the `menu` key entirely, is a
+ // malformed response -- surface it as a service failure rather than silently
+ // reporting "no menu found" (which is reserved for an explicit `null`).
+ if (typeof data !== "object" || data === null || !("menu" in data)) {
+ throw new Error(
+ "Menu extraction failed: service returned an unexpected response shape (missing 'menu')",
+ );
+ }
+
+ if (data.menu) {
+ document.menu = data.menu;
+ } else {
+ // `menu` is null: the page loaded but is not a menu page.
+ document.warning =
+ "No menu found on this page; it does not appear to be a menu page." +
+ (document.warning ? " " + document.warning : "");
+ }
+ return document;
+}
diff --git a/apps/api/src/types/menu.ts b/apps/api/src/types/menu.ts
new file mode 100644
index 000000000..79be6e2de
--- /dev/null
+++ b/apps/api/src/types/menu.ts
@@ -0,0 +1,51 @@
+import { z } from "zod";
+
+// Canonical menu shape, mirroring the menu-extraction service's output
+// (menu-search `Menu`). A menu is a merchant profile plus an ordered list of
+// sections, each holding items. Per-item pricing, availability, and images live
+// on the item.
+const menuPriceSchema = z.object({
+ amount: z.number(),
+ currency: z.string().optional(),
+ formatted: z.string().optional(),
+});
+const menuAvailabilitySchema = z.object({
+ inStock: z.boolean(),
+ text: z.string().optional(),
+});
+const menuItemSchema = z.object({
+ id: z.string(),
+ name: z.string(),
+ description: z.string().optional(),
+ images: z
+ .array(z.object({ url: z.string(), alt: z.string().optional() }))
+ .default([]),
+ price: menuPriceSchema.optional(),
+ availability: menuAvailabilitySchema,
+ dietary: z.array(z.string()).default([]),
+ calories: z.number().optional(),
+ optionGroups: z.array(z.unknown()).default([]),
+ identifiers: z.object({ merchantItemId: z.string().optional() }).default({}),
+ url: z.string().optional(),
+ sourceUrl: z.string(),
+});
+const menuSectionSchema = z.object({
+ id: z.string(),
+ name: z.string(),
+ description: z.string().optional(),
+ items: z.array(menuItemSchema),
+});
+const menuProfileSchema = z.object({
+ isMenu: z.boolean(),
+ confidence: z.number(),
+ merchant: z.object({
+ name: z.string(),
+ type: z.string().nullable().optional(),
+ location: z.unknown().optional(),
+ }),
+ currency: z.string().nullable().optional(),
+ sections: z.array(menuSectionSchema),
+ sourceUrl: z.string(),
+});
+
+export type MenuProfile = z.infer<typeof menuProfileSchema>;
diff --git a/apps/dot-net-sdk/Firecrawl.Tests/ModelsTests.cs b/apps/dot-net-sdk/Firecrawl.Tests/ModelsTests.cs
index 32aed1092..19b83f883 100644
--- a/apps/dot-net-sdk/Firecrawl.Tests/ModelsTests.cs
+++ b/apps/dot-net-sdk/Firecrawl.Tests/ModelsTests.cs
@@ -192,6 +192,80 @@ public class ModelsTests
Assert.Equal("Front", variant.Images[0].Alt);
}
+ [Fact]
+ public void Document_DeserializesMenuCorrectly()
+ {
+ var json = """
+ {
+ "markdown": "# Menu",
+ "menu": {
+ "isMenu": true,
+ "confidence": 0.95,
+ "merchant": { "name": "Acme Diner", "type": "restaurant" },
+ "currency": "USD",
+ "sourceUrl": "https://example.com/restaurant/1",
+ "sections": [
+ {
+ "id": "s1",
+ "name": "Appetizers",
+ "description": "Starters",
+ "items": [
+ {
+ "id": "i1",
+ "name": "Garlic Bread",
+ "description": "Toasted",
+ "images": [ { "url": "https://example.com/i1.jpg", "alt": "Bread" } ],
+ "price": { "amount": 5.99, "currency": "USD", "formatted": "$5.99" },
+ "availability": { "inStock": true, "text": "Available" },
+ "dietary": [ "vegetarian" ],
+ "calories": 320,
+ "optionGroups": [],
+ "identifiers": { "merchantItemId": "MID-1" },
+ "url": "https://example.com/item/1",
+ "sourceUrl": "https://example.com/restaurant/1"
+ }
+ ]
+ }
+ ]
+ }
+ }
+ """;
+
+ var doc = JsonSerializer.Deserialize<Document>(json, JsonOptions);
+ Assert.NotNull(doc);
+ Assert.NotNull(doc.Menu);
+ Assert.True(doc.Menu.IsMenu);
+ Assert.Equal(0.95, doc.Menu.Confidence);
+ Assert.Equal("USD", doc.Menu.Currency);
+ Assert.Equal("https://example.com/restaurant/1", doc.Menu.SourceUrl);
+ Assert.NotNull(doc.Menu.Merchant);
+ Assert.Equal("Acme Diner", doc.Menu.Merchant.Name);
+ Assert.Equal("restaurant", doc.Menu.Merchant.Type);
+ Assert.NotNull(doc.Menu.Sections);
+ Assert.Single(doc.Menu.Sections);
+ var section = doc.Menu.Sections[0];
+ Assert.Equal("s1", section.Id);
+ Assert.Equal("Appetizers", section.Name);
+ Assert.Single(section.Items);
+ var item = section.Items[0];
+ Assert.Equal("i1", item.Id);
+ Assert.Equal("Garlic Bread", item.Name);
+ Assert.NotNull(item.Price);
+ Assert.Equal(5.99, item.Price.Amount);
+ Assert.Equal("USD", item.Price.Currency);
+ Assert.NotNull(item.Availability);
+ Assert.True(item.Availability.InStock);
+ Assert.NotNull(item.Dietary);
+ Assert.Contains("vegetarian", item.Dietary);
+ Assert.Equal(320, item.Calories);
+ Assert.NotNull(item.Identifiers);
+ Assert.Equal("MID-1", item.Identifiers.MerchantItemId);
+ Assert.NotNull(item.Images);
+ Assert.Single(item.Images);
+ Assert.Equal("Bread", item.Images[0].Alt);
+ Assert.Equal("https://example.com/restaurant/1", item.SourceUrl);
+ }
+
[Fact]
public void Document_IgnoresUnknownProperties()
{
diff --git a/apps/dot-net-sdk/Firecrawl.Tests/ParseTests.cs b/apps/dot-net-sdk/Firecrawl.Tests/ParseTests.cs
index 2ebba52c4..00f145294 100644
--- a/apps/dot-net-sdk/Firecrawl.Tests/ParseTests.cs
+++ b/apps/dot-net-sdk/Firecrawl.Tests/ParseTests.cs
@@ -91,6 +91,18 @@ public class ParseTests
Assert.Contains("product", ex.Message);
}
+ [Fact]
+ public void ParseOptions_Validate_RejectsMenuFormat()
+ {
+ var options = new ParseOptions
+ {
+ Formats = new List<object> { "markdown", "menu" }
+ };
+
+ var ex = Assert.Throws<ArgumentException>(() => options.Validate());
+ Assert.Contains("menu", ex.Message);
+ }
+
[Fact]
public void ParseOptions_Validate_RejectsUnsupportedProxy()
{
diff --git a/apps/dot-net-sdk/Firecrawl/Firecrawl.csproj b/apps/dot-net-sdk/Firecrawl/Firecrawl.csproj
index 1b26b813d..b9126f7da 100644
--- a/apps/dot-net-sdk/Firecrawl/Firecrawl.csproj
+++ b/apps/dot-net-sdk/Firecrawl/Firecrawl.csproj
@@ -8,7 +8,7 @@
<!-- NuGet package metadata -->
<PackageId>firecrawl-sdk</PackageId>
- <Version>1.8.1</Version>
+ <Version>1.8.2</Version>
<Authors>Firecrawl</Authors>
<Company>Firecrawl</Company>
<Description>.NET SDK for the Firecrawl API - web scraping, crawling, and data extraction</Description>
diff --git a/apps/dot-net-sdk/Firecrawl/FirecrawlClient.cs b/apps/dot-net-sdk/Firecrawl/FirecrawlClient.cs
index 1f0e3a460..c7210428e 100644
--- a/apps/dot-net-sdk/Firecrawl/FirecrawlClient.cs
+++ b/apps/dot-net-sdk/Firecrawl/FirecrawlClient.cs
@@ -259,7 +259,7 @@ public class FirecrawlClient
/// </summary>
/// <param name="file">The file to upload.</param>
/// <param name="options">Optional parse options. Browser-only formats
- /// (changeTracking, screenshot, branding, product), actions, waitFor, location,
+ /// (changeTracking, screenshot, branding, product, menu), actions, waitFor, location,
/// and mobile are rejected.</param>
/// <param name="cancellationToken">Cancellation token.</param>
public async Task<Document> ParseAsync(
diff --git a/apps/dot-net-sdk/Firecrawl/Models/Document.cs b/apps/dot-net-sdk/Firecrawl/Models/Document.cs
index 9054c8db1..7aa7ef69a 100644
--- a/apps/dot-net-sdk/Firecrawl/Models/Document.cs
+++ b/apps/dot-net-sdk/Firecrawl/Models/Document.cs
@@ -60,4 +60,7 @@ public class Document
[JsonPropertyName("product")]
public ProductProfile? Product { get; set; }
+
+ [JsonPropertyName("menu")]
+ public MenuProfile? Menu { get; set; }
}
diff --git a/apps/dot-net-sdk/Firecrawl/Models/MenuProfile.cs b/apps/dot-net-sdk/Firecrawl/Models/MenuProfile.cs
new file mode 100644
index 000000000..5b7852478
--- /dev/null
+++ b/apps/dot-net-sdk/Firecrawl/Models/MenuProfile.cs
@@ -0,0 +1,164 @@
+using System.Text.Json;
+using System.Text.Json.Serialization;
+
+namespace Firecrawl.Models;
+
+/// <summary>
+/// Structured menu information extracted via the <c>menu</c> scrape format.
+/// </summary>
+public class MenuProfile
+{
+ [JsonPropertyName("isMenu")]
+ public bool IsMenu { get; set; }
+
+ [JsonPropertyName("confidence")]
+ public double Confidence { get; set; }
+
+ [JsonPropertyName("merchant")]
+ public MenuMerchant Merchant { get; set; } = new();
+
+ [JsonPropertyName("currency")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public string? Currency { get; set; }
+
+ [JsonPropertyName("sections")]
+ public List<MenuSection> Sections { get; set; } = new();
+
+ [JsonPropertyName("sourceUrl")]
+ public string SourceUrl { get; set; } = string.Empty;
+}
+
+/// <summary>
+/// The merchant a menu belongs to.
+/// </summary>
+public class MenuMerchant
+{
+ [JsonPropertyName("name")]
+ public string Name { get; set; } = string.Empty;
+
+ [JsonPropertyName("type")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public string? Type { get; set; }
+
+ [JsonPropertyName("location")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public JsonElement? Location { get; set; }
+}
+
+/// <summary>
+/// An ordered section of a menu (e.g. "Appetizers"), holding items.
+/// </summary>
+public class MenuSection
+{
+ [JsonPropertyName("id")]
+ public string Id { get; set; } = string.Empty;
+
+ [JsonPropertyName("name")]
+ public string Name { get; set; } = string.Empty;
+
+ [JsonPropertyName("description")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public string? Description { get; set; }
+
+ [JsonPropertyName("items")]
+ public List<MenuItem> Items { get; set; } = new();
+}
+
+/// <summary>
+/// A single item on a menu, with its own pricing, availability, and images.
+/// </summary>
+public class MenuItem
+{
+ [JsonPropertyName("id")]
+ public string Id { get; set; } = string.Empty;
+
+ [JsonPropertyName("name")]
+ public string Name { get; set; } = string.Empty;
+
+ [JsonPropertyName("description")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public string? Description { get; set; }
+
+ [JsonPropertyName("images")]
+ public List<MenuImage> Images { get; set; } = new();
+
+ [JsonPropertyName("price")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public MenuPrice? Price { get; set; }
+
+ [JsonPropertyName("availability")]
+ public MenuAvailability Availability { get; set; } = new();
+
+ [JsonPropertyName("dietary")]
+ public List<string> Dietary { get; set; } = new();
+
+ [JsonPropertyName("calories")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public double? Calories { get; set; }
+
+ [JsonPropertyName("optionGroups")]
+ public List<object> OptionGroups { get; set; } = new();
+
+ [JsonPropertyName("identifiers")]
+ public MenuItemIdentifiers Identifiers { get; set; } = new();
+
+ [JsonPropertyName("url")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public string? Url { get; set; }
+
+ [JsonPropertyName("sourceUrl")]
+ public string SourceUrl { get; set; } = string.Empty;
+}
+
+/// <summary>
+/// An image associated with a menu item.
+/// </summary>
+public class MenuImage
+{
+ [JsonPropertyName("url")]
+ public string Url { get; set; } = string.Empty;
+
+ [JsonPropertyName("alt")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public string? Alt { get; set; }
+}
+
+/// <summary>
+/// A monetary price for a menu item.
+/// </summary>
+public class MenuPrice
+{
+ [JsonPropertyName("amount")]
+ public double Amount { get; set; }
+
+ [JsonPropertyName("currency")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public string? Currency { get; set; }
+
+ [JsonPropertyName("formatted")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public string? Formatted { get; set; }
+}
+
+/// <summary>
+/// Availability information for a menu item.
+/// </summary>
+public class MenuAvailability
+{
+ [JsonPropertyName("inStock")]
+ public bool InStock { get; set; }
+
+ [JsonPropertyName("text")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public string? Text { get; set; }
+}
+
+/// <summary>
+/// External identifiers for a menu item.
+/// </summary>
+public class MenuItemIdentifiers
+{
+ [JsonPropertyName("merchantItemId")]
+ [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+ public string? MerchantItemId { get; set; }
+}
diff --git a/apps/dot-net-sdk/Firecrawl/Models/ParseOptions.cs b/apps/dot-net-sdk/Firecrawl/Models/ParseOptions.cs
index 920ff62b4..a77fb9dc7 100644
--- a/apps/dot-net-sdk/Firecrawl/Models/ParseOptions.cs
+++ b/apps/dot-net-sdk/Firecrawl/Models/ParseOptions.cs
@@ -8,7 +8,7 @@ namespace Firecrawl.Models;
///
/// <para>
/// Parse does not support browser-rendering formats/options such as change
-/// tracking, screenshot, branding, product, actions, waitFor, location, or mobile.
+/// tracking, screenshot, branding, product, menu, actions, waitFor, location, or mobile.
/// These are rejected client-side in <see cref="Validate"/>.
/// </para>
/// </summary>
@@ -22,6 +22,7 @@ public class ParseOptions
"screenshot@fullPage",
"branding",
"product",
+ "menu",
};
internal static readonly HashSet<string> SupportedProxies = new(StringComparer.OrdinalIgnoreCase)
diff --git a/apps/dot-net-sdk/README.md b/apps/dot-net-sdk/README.md
index 9a894b272..556670385 100644
--- a/apps/dot-net-sdk/README.md
+++ b/apps/dot-net-sdk/README.md
@@ -98,6 +98,20 @@ var doc = await client.ScrapeAsync("https://example.com/product/123",
Console.WriteLine(doc.Product);
```
+### Menu Extraction
+
+Use the `menu` format on restaurant/merchant pages to get structured menu
+extraction (a merchant profile plus ordered sections, each holding items with
+their own price, availability, and images) on the document's `Menu` property. It
+is the deterministic counterpart to the LLM-based `json` format.
+
+```csharp
+var doc = await client.ScrapeAsync("https://example.com/restaurant/123",
+ new ScrapeOptions { Formats = new List<object> { "menu" } });
+
+Console.WriteLine(doc.Menu);
+```
+
### Crawl
```csharp
diff --git a/apps/elixir-sdk/README.md b/apps/elixir-sdk/README.md
index 29a1c9206..2bf45feca 100644
--- a/apps/elixir-sdk/README.md
+++ b/apps/elixir-sdk/README.md
@@ -58,6 +58,14 @@ All params are passed as keyword lists with snake_case keys. Invalid keys, missi
formats: ["product"]
)
+# Structured menu extraction from restaurant/menu pages
+# `menu` pulls structured menu data (sections, items, prices). Read the
+# result from the response body's "menu" key.
+{:ok, response} = Firecrawl.scrape_and_extract_from_url(
+ url: "https://example.com/menu",
+ formats: ["menu"]
+)
+
# Crawl a site
{:ok, response} = Firecrawl.crawl_urls(
url: "https://example.com",
diff --git a/apps/elixir-sdk/mix.exs b/apps/elixir-sdk/mix.exs
index c0c007082..e978dfbc9 100644
--- a/apps/elixir-sdk/mix.exs
+++ b/apps/elixir-sdk/mix.exs
@@ -1,7 +1,7 @@
defmodule Firecrawl.MixProject do
use Mix.Project
- @version "1.7.1"
+ @version "1.7.2"
@source_url "https://github.com/firecrawl/firecrawl/tree/main/apps/elixir-sdk"
def project do
diff --git a/apps/go-sdk/README.md b/apps/go-sdk/README.md
index e42dbb633..ef85f98df 100644
--- a/apps/go-sdk/README.md
+++ b/apps/go-sdk/README.md
@@ -124,6 +124,22 @@ if err != nil {
fmt.Println(doc.Product)
```
+### Menu Extraction
+
+Use the `menu` format on menu pages for structured menu extraction
+(merchant, sections, items, prices, availability). The result is returned on the
+document's `Menu` field. This is the deterministic counterpart to the LLM-based `json` format.
+
+```go
+doc, err := client.Scrape(ctx, "https://example.com/menu", &firecrawl.ScrapeOptions{
+ Formats: []string{"menu"},
+})
+if err != nil {
+ return err
+}
+fmt.Println(doc.Menu)
+```
+
#### Interactive Browser
Execute code in a scrape-bound browser session:
@@ -142,7 +158,7 @@ deleteResp, err := client.StopInteractiveBrowser(ctx, scrapeJobID)
Upload a local file (`html`, `pdf`, `docx`, etc.) via multipart form data and
parse it synchronously. Parse options intentionally exclude browser-only
-features such as change tracking, screenshot, branding, product, audio, video, actions,
+features such as change tracking, screenshot, branding, product, menu, audio, video, actions,
waitFor, location, and mobile. The `Proxy` option only accepts `"auto"` or `"basic"`.
```go
diff --git a/apps/go-sdk/models.go b/apps/go-sdk/models.go
index 67c5c487d..47626b925 100644
--- a/apps/go-sdk/models.go
+++ b/apps/go-sdk/models.go
@@ -23,6 +23,7 @@ type Document struct {
ChangeTracking map[string]interface{} `json:"changeTracking,omitempty"`
Branding map[string]interface{} `json:"branding,omitempty"`
Product *ProductProfile `json:"product,omitempty"`
+ Menu *MenuProfile `json:"menu,omitempty"`
}
// ProductProfile represents structured product data extracted from a page
@@ -72,6 +73,72 @@ type ProductVariant struct {
Images []ProductImage `json:"images,omitempty"`
}
+// MenuProfile represents structured menu data extracted from a page
+// via the `menu` scrape format.
+type MenuProfile struct {
+ IsMenu bool `json:"isMenu"`
+ Confidence float64 `json:"confidence"`
+ Merchant MenuMerchant `json:"merchant"`
+ Currency string `json:"currency,omitempty"`
+ Sections []MenuSection `json:"sections,omitempty"`
+ SourceURL string `json:"sourceUrl"`
+}
+
+// MenuMerchant represents the merchant a menu belongs to.
+type MenuMerchant struct {
+ Name string `json:"name"`
+ Type string `json:"type,omitempty"`
+ Location interface{} `json:"location,omitempty"`
+}
+
+// MenuSection represents an ordered grouping of menu items.
+type MenuSection struct {
+ ID string `json:"id"`
+ Name string `json:"name"`
+ Description string `json:"description,omitempty"`
+ Items []MenuItem `json:"items,omitempty"`
+}
+
+// MenuItem represents a single item on a menu.
+type MenuItem struct {
+ ID string `json:"id"`
+ Name string `json:"name"`
+ Description string `json:"description,omitempty"`
+ Images []MenuImage `json:"images,omitempty"`
+ Price *MenuPrice `json:"price,omitempty"`
+ Availability MenuAvailability `json:"availability"`
+ Dietary []string `json:"dietary,omitempty"`
+ Calories *float64 `json:"calories,omitempty"`
+ OptionGroups []interface{} `json:"optionGroups,omitempty"`
+ Identifiers MenuItemIdentifiers `json:"identifiers"`
+ URL string `json:"url,omitempty"`
+ SourceURL string `json:"sourceUrl"`
+}
+
+// MenuImage is a single menu item image.
+type MenuImage struct {
+ URL string `json:"url"`
+ Alt string `json:"alt,omitempty"`
+}
+
+// MenuPrice represents a price for a menu item.
+type MenuPrice struct {
+ Amount float64 `json:"amount"`
+ Currency string `json:"currency,omitempty"`
+ Formatted string `json:"formatted,omitempty"`
+}
+
+// MenuAvailability represents stock availability for a menu item.
+type MenuAvailability struct {
+ InStock bool `json:"inStock"`
+ Text string `json:"text,omitempty"`
+}
+
+// MenuItemIdentifiers holds merchant-specific identifiers for a menu item.
+type MenuItemIdentifiers struct {
+ MerchantItemID string `json:"merchantItemId,omitempty"`
+}
+
// PaperResult represents a ranked research paper result.
type PaperResult struct {
PaperID string `json:"paperId"`
diff --git a/apps/go-sdk/parse.go b/apps/go-sdk/parse.go
index 4b3e3632e..57ca32806 100644
--- a/apps/go-sdk/parse.go
+++ b/apps/go-sdk/parse.go
@@ -54,7 +54,7 @@ func NewParseFileFromBytes(filename string, content []byte) *ParseFile {
// ParseOptions configures a parse request.
//
// Parse does not support browser-rendering features (actions, waitFor, location,
-// mobile) nor the screenshot, branding, product, or changeTracking formats. The proxy
+// mobile) nor the screenshot, branding, product, menu, or changeTracking formats. The proxy
// field only accepts "auto" or "basic".
type ParseOptions struct {
Formats []string `json:"-"`
diff --git a/apps/go-sdk/parse_test.go b/apps/go-sdk/parse_test.go
index 7114c124d..1bce28ad8 100644
--- a/apps/go-sdk/parse_test.go
+++ b/apps/go-sdk/parse_test.go
@@ -2,6 +2,7 @@ package firecrawl
import (
"context"
+ "encoding/json"
"io"
"mime"
"mime/multipart"
@@ -132,3 +133,63 @@ func TestParseRejectsEmptyContent(t *testing.T) {
t.Fatalf("expected error for empty content")
}
}
+
+func TestDocumentUnmarshalsMenu(t *testing.T) {
+ raw := []byte(`{
+ "markdown": "# Cafe",
+ "menu": {
+ "isMenu": true,
+ "confidence": 0.92,
+ "merchant": {"name": "Test Cafe", "type": "restaurant"},
+ "currency": "USD",
+ "sourceUrl": "https://example.com/menu",
+ "sections": [
+ {
+ "id": "drinks",
+ "name": "Drinks",
+ "items": [
+ {
+ "id": "latte",
+ "name": "Latte",
+ "availability": {"inStock": true},
+ "price": {"amount": 4.5, "currency": "USD"},
+ "identifiers": {"merchantItemId": "sku-1"},
+ "sourceUrl": "https://example.com/menu"
+ }
+ ]
+ }
+ ]
+ }
+ }`)
+
+ var doc Document
+ if err := json.Unmarshal(raw, &doc); err != nil {
+ t.Fatalf("Unmarshal: %v", err)
+ }
+
+ if doc.Menu == nil {
+ t.Fatalf("expected menu, got nil")
+ }
+ if !doc.Menu.IsMenu {
+ t.Errorf("isMenu = false, want true")
+ }
+ if doc.Menu.Confidence != 0.92 {
+ t.Errorf("confidence = %v, want 0.92", doc.Menu.Confidence)
+ }
+ if doc.Menu.Merchant.Name != "Test Cafe" {
+ t.Errorf("merchant.name = %q, want %q", doc.Menu.Merchant.Name, "Test Cafe")
+ }
+ if len(doc.Menu.Sections) != 1 {
+ t.Fatalf("sections = %d, want 1", len(doc.Menu.Sections))
+ }
+ items := doc.Menu.Sections[0].Items
+ if len(items) != 1 {
+ t.Fatalf("items = %d, want 1", len(items))
+ }
+ if items[0].Name != "Latte" {
+ t.Errorf("item name = %q, want %q", items[0].Name, "Latte")
+ }
+ if !items[0].Availability.InStock {
+ t.Errorf("item availability inStock = false, want true")
+ }
+}
diff --git a/apps/go-sdk/version.go b/apps/go-sdk/version.go
index 1cdf6c43e..237757df3 100644
--- a/apps/go-sdk/version.go
+++ b/apps/go-sdk/version.go
@@ -9,4 +9,4 @@ package firecrawl
// Bump this when preparing a new release. The publish-go-sdk GitHub workflow
// reads this value and creates the corresponding monorepo-prefixed tag on
// merge to main.
-const Version = "1.7.1"
+const Version = "1.7.2"
diff --git a/apps/java-sdk/README.md b/apps/java-sdk/README.md
index 436a7f4c6..0a80b015a 100644
--- a/apps/java-sdk/README.md
+++ b/apps/java-sdk/README.md
@@ -217,6 +217,19 @@ Document doc = client.scrape("https://example.com/product",
System.out.println(doc.getProduct());
```
+#### Menu Extraction
+
+Use the `menu` format to get structured menu data (merchant profile plus ordered sections, each holding items with their own price, availability, and images) from restaurant and menu pages, available on the document's `getMenu()`.
+
+```java
+Document doc = client.scrape("https://example.com/menu",
+ ScrapeOptions.builder()
+ .formats(List.of("menu"))
+ .build());
+
+System.out.println(doc.getMenu());
+```
+
#### Scrape-Bound Interactive Session
Run browser automation against the page context captured by a scrape job:
diff --git a/apps/java-sdk/build.gradle.kts b/apps/java-sdk/build.gradle.kts
index ba1573566..91808bf8b 100644
--- a/apps/java-sdk/build.gradle.kts
+++ b/apps/java-sdk/build.gradle.kts
@@ -4,7 +4,7 @@ plugins {
}
group = "com.firecrawl"
-version = "1.10.1"
+version = "1.10.2"
java {
sourceCompatibility = JavaVersion.VERSION_11
diff --git a/apps/java-sdk/src/main/java/com/firecrawl/models/Document.java b/apps/java-sdk/src/main/java/com/firecrawl/models/Document.java
index 90b136f87..48b10b180 100644
--- a/apps/java-sdk/src/main/java/com/firecrawl/models/Document.java
+++ b/apps/java-sdk/src/main/java/com/firecrawl/models/Document.java
@@ -29,6 +29,7 @@ public class Document {
private Map<String, Object> changeTracking;
private Map<String, Object> branding;
private Product product;
+ private Menu menu;
public String getMarkdown() { return markdown; }
public String getHtml() { return html; }
@@ -49,6 +50,7 @@ public class Document {
public Map<String, Object> getChangeTracking() { return changeTracking; }
public Map<String, Object> getBranding() { return branding; }
public Product getProduct() { return product; }
+ public Menu getMenu() { return menu; }
@Override
public String toString() {
diff --git a/apps/java-sdk/src/main/java/com/firecrawl/models/Menu.java b/apps/java-sdk/src/main/java/com/firecrawl/models/Menu.java
new file mode 100644
index 000000000..6e031797c
--- /dev/null
+++ b/apps/java-sdk/src/main/java/com/firecrawl/models/Menu.java
@@ -0,0 +1,33 @@
+package com.firecrawl.models;
+
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
+import com.fasterxml.jackson.annotation.JsonProperty;
+import java.util.List;
+
+/**
+ * Structured menu information extracted by the {@code menu} scrape format.
+ */
+@JsonIgnoreProperties(ignoreUnknown = true)
+public class Menu {
+
+ @JsonProperty("isMenu")
+ private boolean isMenu;
+ private double confidence;
+ private String currency;
+ private String sourceUrl;
+ private MenuMerchant merchant;
+ private List<MenuSection> sections;
+
+ @JsonProperty("isMenu")
+ public boolean isMenu() { return isMenu; }
+ public double getConfidence() { return confidence; }
+ public String getCurrency() { return currency; }
+ public String getSourceUrl() { return sourceUrl; }
+ public MenuMerchant getMerchant() { return merchant; }
+ public List<MenuSection> getSections() { return sections; }
+
+ @Override
+ public String toString() {
+ return "Menu{isMenu=" + isMenu + ", sourceUrl=" + sourceUrl + "}";
+ }
+}
diff --git a/apps/java-sdk/src/main/java/com/firecrawl/models/MenuAvailability.java b/apps/java-sdk/src/main/java/com/firecrawl/models/MenuAvailability.java
new file mode 100644
index 000000000..620e5b105
--- /dev/null
+++ b/apps/java-sdk/src/main/java/com/firecrawl/models/MenuAvailability.java
@@ -0,0 +1,21 @@
+package com.firecrawl.models;
+
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
+
+/**
+ * Availability information for a menu item extracted by the {@code menu} scrape format.
+ */
+@JsonIgnoreProperties(ignoreUnknown = true)
+public class MenuAvailability {
+
+ private boolean inStock;
+ private String text;
+
+ public boolean isInStock() { return inStock; }
+ public String getText() { return text; }
+
+ @Override
+ public String toString() {
+ return "MenuAvailability{inStock=" + inStock + "}";
+ }
+}
diff --git a/apps/java-sdk/src/main/java/com/firecrawl/models/MenuImage.java b/apps/java-sdk/src/main/java/com/firecrawl/models/MenuImage.java
new file mode 100644
index 000000000..ce86746b3
--- /dev/null
+++ b/apps/java-sdk/src/main/java/com/firecrawl/models/MenuImage.java
@@ -0,0 +1,21 @@
+package com.firecrawl.models;
+
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
+
+/**
+ * An image associated with a menu item extracted by the {@code menu} scrape format.
+ */
+@JsonIgnoreProperties(ignoreUnknown = true)
+public class MenuImage {
+
+ private String url;
+ private String alt;
+
+ public String getUrl() { return url; }
+ public String getAlt() { return alt; }
+
+ @Override
+ public String toString() {
+ return "MenuImage{url=" + url + "}";
+ }
+}
diff --git a/apps/java-sdk/src/main/java/com/firecrawl/models/MenuItem.java b/apps/java-sdk/src/main/java/com/firecrawl/models/MenuItem.java
new file mode 100644
index 000000000..08b099dc0
--- /dev/null
+++ b/apps/java-sdk/src/main/java/com/firecrawl/models/MenuItem.java
@@ -0,0 +1,42 @@
+package com.firecrawl.models;
+
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
+import java.util.List;
+
+/**
+ * An item on a menu extracted by the {@code menu} scrape format.
+ */
+@JsonIgnoreProperties(ignoreUnknown = true)
+public class MenuItem {
+
+ private String id;
+ private String name;
+ private String description;
+ private List<MenuImage> images;
+ private MenuPrice price;
+ private MenuAvailability availability;
+ private List<String> dietary;
+ private Double calories;
+ private List<Object> optionGroups;
+ private MenuItemIdentifiers identifiers;
+ private String url;
+ private String sourceUrl;
+
+ public String getId() { return id; }
+ public String getName() { return name; }
+ public String getDescription() { return description; }
+ public List<MenuImage> getImages() { return images; }
+ public MenuPrice getPrice() { return price; }
+ public MenuAvailability getAvailability() { return availability; }
+ public List<String> getDietary() { return dietary; }
+ public Double getCalories() { return calories; }
+ public List<Object> getOptionGroups() { return optionGroups; }
+ public MenuItemIdentifiers getIdentifiers() { return identifiers; }
+ public String getUrl() { return url; }
+ public String getSourceUrl() { return sourceUrl; }
+
+ @Override
+ public String toString() {
+ return "MenuItem{id=" + id + ", name=" + name + "}";
+ }
+}
diff --git a/apps/java-sdk/src/main/java/com/firecrawl/models/MenuItemIdentifiers.java b/apps/java-sdk/src/main/java/com/firecrawl/models/MenuItemIdentifiers.java
new file mode 100644
index 000000000..4ba5a8beb
--- /dev/null
+++ b/apps/java-sdk/src/main/java/com/firecrawl/models/MenuItemIdentifiers.java
@@ -0,0 +1,19 @@
+package com.firecrawl.models;
+
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
+
+/**
+ * Identifiers for a menu item extracted by the {@code menu} scrape format.
+ */
+@JsonIgnoreProperties(ignoreUnknown = true)
+public class MenuItemIdentifiers {
+
+ private String merchantItemId;
+
+ public String getMerchantItemId() { return merchantItemId; }
+
+ @Override
+ public String toString() {
+ return "MenuItemIdentifiers{merchantItemId=" + merchantItemId + "}";
+ }
+}
diff --git a/apps/java-sdk/src/main/java/com/firecrawl/models/MenuMerchant.java b/apps/java-sdk/src/main/java/com/firecrawl/models/MenuMerchant.java
new file mode 100644
index 000000000..d9e58af09
--- /dev/null
+++ b/apps/java-sdk/src/main/java/com/firecrawl/models/MenuMerchant.java
@@ -0,0 +1,23 @@
+package com.firecrawl.models;
+
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
+
+/**
+ * The merchant a menu belongs to, extracted by the {@code menu} scrape format.
+ */
+@JsonIgnoreProperties(ignoreUnknown = true)
+public class MenuMerchant {
+
+ private String name;
+ private String type;
+ private Object location;
+
+ public String getName() { return name; }
+ public String getType() { return type; }
+ public Object getLocation() { return location; }
+
+ @Override
+ public String toString() {
+ return "MenuMerchant{name=" + name + "}";
+ }
+}
diff --git a/apps/java-sdk/src/main/java/com/firecrawl/models/MenuPrice.java b/apps/java-sdk/src/main/java/com/firecrawl/models/MenuPrice.java
new file mode 100644
index 000000000..13fa03543
--- /dev/null
+++ b/apps/java-sdk/src/main/java/com/firecrawl/models/MenuPrice.java
@@ -0,0 +1,23 @@
+package com.firecrawl.models;
+
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
+
+/**
+ * A price associated with a menu item extracted by the {@code menu} scrape format.
+ */
+@JsonIgnoreProperties(ignoreUnknown = true)
+public class MenuPrice {
+
+ private double amount;
+ private String currency;
+ private String formatted;
+
+ public double getAmount() { return amount; }
+ public String getCurrency() { return currency; }
+ public String getFormatted() { return formatted; }
+
+ @Override
+ public String toString() {
+ return "MenuPrice{formatted=" + formatted + "}";
+ }
+}
diff --git a/apps/java-sdk/src/main/java/com/firecrawl/models/MenuSection.java b/apps/java-sdk/src/main/java/com/firecrawl/models/MenuSection.java
new file mode 100644
index 000000000..74137a48b
--- /dev/null
+++ b/apps/java-sdk/src/main/java/com/firecrawl/models/MenuSection.java
@@ -0,0 +1,26 @@
+package com.firecrawl.models;
+
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
+import java.util.List;
+
+/**
+ * A section of a menu extracted by the {@code menu} scrape format.
+ */
+@JsonIgnoreProperties(ignoreUnknown = true)
+public class MenuSection {
+
+ private String id;
+ private String name;
+ private String description;
+ private List<MenuItem> items;
+
+ public String getId() { return id; }
+ public String getName() { return name; }
+ public String getDescription() { return description; }
+ public List<MenuItem> getItems() { return items; }
+
+ @Override
+ public String toString() {
+ return "MenuSection{id=" + id + ", name=" + name + "}";
+ }
+}
diff --git a/apps/java-sdk/src/main/java/com/firecrawl/models/ParseOptions.java b/apps/java-sdk/src/main/java/com/firecrawl/models/ParseOptions.java
index c1b68876c..079bc29d4 100644
--- a/apps/java-sdk/src/main/java/com/firecrawl/models/ParseOptions.java
+++ b/apps/java-sdk/src/main/java/com/firecrawl/models/ParseOptions.java
@@ -12,7 +12,7 @@ import java.util.Map;
* Options for parsing uploaded files via /v2/parse.
*
* <p>Parse does not support browser-rendering formats/options such as
- * change tracking, screenshot, branding, product, audio, video, actions, waitFor, location, or mobile.
+ * change tracking, screenshot, branding, product, menu, audio, video, actions, waitFor, location, or mobile.
*/
@JsonInclude(JsonInclude.Include.NON_NULL)
public class ParseOptions {
@@ -94,6 +94,7 @@ public class ParseOptions {
|| normalized.equals("screenshot@fullPage")
|| normalized.equals("branding")
|| normalized.equals("product")
+ || normalized.equals("menu")
|| normalized.equals("audio")
|| normalized.equals("video");
}
diff --git a/apps/java-sdk/src/test/java/com/firecrawl/FirecrawlClientTest.java b/apps/java-sdk/src/test/java/com/firecrawl/FirecrawlClientTest.java
index 37ac688fe..8ef13cd6c 100644
--- a/apps/java-sdk/src/test/java/com/firecrawl/FirecrawlClientTest.java
+++ b/apps/java-sdk/src/test/java/com/firecrawl/FirecrawlClientTest.java
@@ -252,6 +252,64 @@ class FirecrawlClientTest {
);
}
+ @Test
+ void testParseOptionsRejectsMenuFormat() {
+ assertThrows(IllegalArgumentException.class, () ->
+ ParseOptions.builder()
+ .formats(List.of("menu"))
+ .build()
+ );
+ }
+
+ @Test
+ void testDocumentDeserializesMenu() throws Exception {
+ String json = "{\"menu\":{"
+ + "\"isMenu\":true,"
+ + "\"confidence\":0.9,"
+ + "\"currency\":\"USD\","
+ + "\"sourceUrl\":\"https://example.com/menu\","
+ + "\"merchant\":{\"name\":\"Joe's Diner\",\"type\":\"restaurant\",\"location\":{\"city\":\"NYC\"}},"
+ + "\"sections\":[{"
+ + "\"id\":\"sec-1\",\"name\":\"Mains\",\"description\":\"Hearty plates\",\"items\":[{"
+ + "\"id\":\"item-1\",\"name\":\"Burger\",\"description\":\"Beef burger\","
+ + "\"images\":[{\"url\":\"https://example.com/burger.jpg\",\"alt\":\"Burger\"}],"
+ + "\"price\":{\"amount\":12.5,\"currency\":\"USD\",\"formatted\":\"$12.50\"},"
+ + "\"availability\":{\"inStock\":true,\"text\":\"Available\"},"
+ + "\"dietary\":[\"halal\"],\"calories\":800,"
+ + "\"optionGroups\":[{\"name\":\"Cheese\"}],"
+ + "\"identifiers\":{\"merchantItemId\":\"sku-99\"},"
+ + "\"url\":\"https://example.com/menu#burger\","
+ + "\"sourceUrl\":\"https://example.com/menu\""
+ + "}]}]}}";
+
+ com.fasterxml.jackson.databind.ObjectMapper mapper = new com.fasterxml.jackson.databind.ObjectMapper();
+ Document doc = mapper.readValue(json, Document.class);
+
+ Menu menu = doc.getMenu();
+ assertNotNull(menu);
+ assertTrue(menu.isMenu());
+ assertEquals(0.9, menu.getConfidence());
+ assertEquals("USD", menu.getCurrency());
+ assertEquals("https://example.com/menu", menu.getSourceUrl());
+ assertEquals("Joe's Diner", menu.getMerchant().getName());
+ assertEquals("restaurant", menu.getMerchant().getType());
+
+ assertEquals(1, menu.getSections().size());
+ MenuSection section = menu.getSections().get(0);
+ assertEquals("sec-1", section.getId());
+ assertEquals("Mains", section.getName());
+
+ MenuItem item = section.getItems().get(0);
+ assertEquals("Burger", item.getName());
+ assertEquals(12.5, item.getPrice().getAmount());
+ assertTrue(item.getAvailability().isInStock());
+ assertEquals(List.of("halal"), item.getDietary());
+ assertEquals(800.0, item.getCalories());
+ assertEquals("https://example.com/burger.jpg", item.getImages().get(0).getUrl());
+ assertEquals("sku-99", item.getIdentifiers().getMerchantItemId());
+ assertEquals("https://example.com/menu", item.getSourceUrl());
+ }
+
@Test
void testParseOptionsBuilderSupportsRedactPII() {
ParseOptions options = ParseOptions.builder()
diff --git a/apps/js-sdk/firecrawl/README.md b/apps/js-sdk/firecrawl/README.md
index f4f2a5f1e..982bf4348 100644
--- a/apps/js-sdk/firecrawl/README.md
+++ b/apps/js-sdk/firecrawl/README.md
@@ -70,6 +70,18 @@ const doc = await app.scrape('https://example.com/product/123', {
console.log(doc.product);
```
+### Menu extraction
+
+Use the `menu` format to deterministically pull a merchant's menu (sections, items, prices, availability) from menu pages — the deterministic counterpart to the LLM-based `json` format.
+
+```js
+const doc = await app.scrape('https://example.com/restaurant/menu', {
+ formats: ['menu'],
+});
+
+console.log(doc.menu);
+```
+
### Parsing uploaded files
Use `parse` to upload a file (`html`, `pdf`, `docx`, etc.) as multipart form data and process it through the same parsing pipeline.
diff --git a/apps/js-sdk/firecrawl/package.json b/apps/js-sdk/firecrawl/package.json
index 9ad1639c5..93c00bce8 100644
--- a/apps/js-sdk/firecrawl/package.json
+++ b/apps/js-sdk/firecrawl/package.json
@@ -1,6 +1,6 @@
{
"name": "@mendable/firecrawl-js",
- "version": "4.28.1",
+ "version": "4.28.2",
"description": "JavaScript SDK for Firecrawl API",
"main": "dist/index.js",
"types": "dist/index.d.ts",
diff --git a/apps/js-sdk/firecrawl/src/__tests__/unit/v2/menu.test.ts b/apps/js-sdk/firecrawl/src/__tests__/unit/v2/menu.test.ts
new file mode 100644
index 000000000..9ca8b3036
--- /dev/null
+++ b/apps/js-sdk/firecrawl/src/__tests__/unit/v2/menu.test.ts
@@ -0,0 +1,213 @@
+import { describe, test, expect, jest } from "@jest/globals";
+import { scrape } from "../../../v2/methods/scrape";
+
+describe("JS SDK v2 menu format", () => {
+ function makeHttp(postImpl: (url: string, data: any) => any) {
+ return { post: jest.fn(async (u: string, d: any) => postImpl(u, d)) } as any;
+ }
+
+ test("scrape with menu format returns menu data", async () => {
+ const mockResponse = {
+ status: 200,
+ data: {
+ success: true,
+ data: {
+ markdown: "# Example Menu",
+ menu: {
+ isMenu: true,
+ confidence: 0.95,
+ currency: "USD",
+ sourceUrl: "https://example.com/menu",
+ merchant: { name: "Acme Diner", type: "restaurant" },
+ sections: [
+ {
+ id: "mains",
+ name: "Mains",
+ description: "Hearty plates",
+ items: [
+ {
+ id: "burger",
+ name: "Classic Burger",
+ description: "Beef patty with cheese",
+ images: [{ url: "https://example.com/burger.jpg", alt: "Burger" }],
+ price: { amount: 12.5, currency: "USD", formatted: "$12.50" },
+ availability: { inStock: true, text: "Available" },
+ dietary: ["contains-gluten"],
+ calories: 800,
+ optionGroups: [],
+ identifiers: { merchantItemId: "ITEM-1" },
+ url: "https://example.com/menu#burger",
+ sourceUrl: "https://example.com/menu"
+ }
+ ]
+ }
+ ]
+ }
+ }
+ }
+ };
+
+ const http = makeHttp(() => mockResponse);
+ const result = await scrape(http, "https://example.com", { formats: ["menu"] });
+
+ expect(result.menu).toBeDefined();
+ expect(result.menu?.isMenu).toBe(true);
+ expect(result.menu?.confidence).toBe(0.95);
+ expect(result.menu?.currency).toBe("USD");
+ expect(result.menu?.merchant?.name).toBe("Acme Diner");
+ expect(result.menu?.merchant?.type).toBe("restaurant");
+ expect(result.menu?.sections?.[0]?.name).toBe("Mains");
+ expect(result.menu?.sections?.[0]?.items?.[0]?.name).toBe("Classic Burger");
+ expect(result.menu?.sections?.[0]?.items?.[0]?.price?.amount).toBe(12.5);
+ expect(result.menu?.sections?.[0]?.items?.[0]?.price?.currency).toBe("USD");
+ expect(result.menu?.sections?.[0]?.items?.[0]?.availability?.inStock).toBe(true);
+ expect(result.menu?.sections?.[0]?.items?.[0]?.images?.[0]?.url).toBe("https://example.com/burger.jpg");
+ expect(result.menu?.sections?.[0]?.items?.[0]?.dietary?.[0]).toBe("contains-gluten");
+ expect(result.menu?.sections?.[0]?.items?.[0]?.identifiers?.merchantItemId).toBe("ITEM-1");
+ });
+
+ test("scrape with menu and markdown formats returns both", async () => {
+ const mockResponse = {
+ status: 200,
+ data: {
+ success: true,
+ data: {
+ markdown: "# Example Content",
+ menu: {
+ isMenu: true,
+ confidence: 0.8,
+ sourceUrl: "https://example.com/cafe",
+ merchant: { name: "Cafe Acme" },
+ sections: [
+ {
+ id: "drinks",
+ name: "Drinks",
+ items: [
+ {
+ id: "coffee",
+ name: "Coffee",
+ images: [],
+ price: { amount: 3.5, currency: "USD" },
+ availability: { inStock: true },
+ dietary: [],
+ optionGroups: [],
+ identifiers: {},
+ sourceUrl: "https://example.com/cafe"
+ }
+ ]
+ }
+ ]
+ }
+ }
+ }
+ };
+
+ const http = makeHttp(() => mockResponse);
+ const result = await scrape(http, "https://example.com", { formats: ["markdown", "menu"] });
+
+ expect(result.markdown).toBe("# Example Content");
+ expect(result.menu).toBeDefined();
+ expect(result.menu?.merchant?.name).toBe("Cafe Acme");
+ expect(result.menu?.sections?.[0]?.items?.[0]?.price?.amount).toBe(3.5);
+ });
+
+ test("scrape without menu format does not return menu", async () => {
+ const mockResponse = {
+ status: 200,
+ data: {
+ success: true,
+ data: {
+ markdown: "# Example"
+ }
+ }
+ };
+
+ const http = makeHttp(() => mockResponse);
+ const result = await scrape(http, "https://example.com", { formats: ["markdown"] });
+
+ expect(result.markdown).toBe("# Example");
+ expect(result.menu).toBeUndefined();
+ });
+
+ test("non-menu page scraped with menu format yields a warning and no menu", async () => {
+ const mockResponse = {
+ status: 200,
+ data: {
+ success: true,
+ data: {
+ markdown: "# Blog Post",
+ warning: "No menu found on this page."
+ }
+ }
+ };
+
+ const http = makeHttp(() => mockResponse);
+ const result = await scrape(http, "https://example.com", { formats: ["menu"] });
+
+ expect(result.menu).toBeUndefined();
+ expect(result.warning).toContain("No menu found");
+ });
+
+ test("menu format with multiple sections and items", async () => {
+ const mockResponse = {
+ status: 200,
+ data: {
+ success: true,
+ data: {
+ menu: {
+ isMenu: true,
+ confidence: 0.9,
+ sourceUrl: "https://example.com/menu",
+ merchant: { name: "Acme Bistro", type: "restaurant", location: { city: "Springfield" } },
+ sections: [
+ {
+ id: "starters",
+ name: "Starters",
+ items: [
+ {
+ id: "soup",
+ name: "Tomato Soup",
+ images: [],
+ price: { amount: 6.0, currency: "USD" },
+ availability: { inStock: true },
+ dietary: ["vegetarian"],
+ optionGroups: [],
+ identifiers: {},
+ sourceUrl: "https://example.com/menu"
+ }
+ ]
+ },
+ {
+ id: "desserts",
+ name: "Desserts",
+ items: [
+ {
+ id: "cake",
+ name: "Chocolate Cake",
+ images: [{ url: "https://example.com/cake.jpg" }],
+ availability: { inStock: false, text: "Sold out" },
+ dietary: [],
+ optionGroups: [],
+ identifiers: {},
+ sourceUrl: "https://example.com/menu"
+ }
+ ]
+ }
+ ]
+ }
+ }
+ }
+ };
+
+ const http = makeHttp(() => mockResponse);
+ const result = await scrape(http, "https://example.com", { formats: ["menu"] });
+
+ expect(result.menu).toBeDefined();
+ expect(result.menu?.sections).toHaveLength(2);
+ expect(result.menu?.sections?.[0]?.items?.[0]?.dietary?.[0]).toBe("vegetarian");
+ expect(result.menu?.sections?.[1]?.name).toBe("Desserts");
+ expect(result.menu?.sections?.[1]?.items?.[0]?.images?.[0]?.url).toBe("https://example.com/cake.jpg");
+ expect(result.menu?.sections?.[1]?.items?.[0]?.availability?.inStock).toBe(false);
+ expect(result.menu?.sections?.[1]?.items?.[0]?.availability?.text).toBe("Sold out");
+ });
+});
diff --git a/apps/js-sdk/firecrawl/src/v2/types.ts b/apps/js-sdk/firecrawl/src/v2/types.ts
index e005ce1d6..744b86262 100644
--- a/apps/js-sdk/firecrawl/src/v2/types.ts
+++ b/apps/js-sdk/firecrawl/src/v2/types.ts
@@ -14,6 +14,7 @@ export type FormatString =
| "attributes"
| "branding"
| "product"
+ | "menu"
| "audio"
| "video";
@@ -468,6 +469,63 @@ export interface ProductProfile {
variants: ProductVariant[];
}
+export interface MenuPrice {
+ amount: number;
+ currency?: string;
+ formatted?: string;
+}
+
+export interface MenuAvailability {
+ inStock: boolean;
+ text?: string;
+}
+
+export interface MenuImage {
+ url: string;
+ alt?: string;
+}
+
+export interface MenuItemIdentifiers {
+ merchantItemId?: string;
+}
+
+export interface MenuItem {
+ id: string;
+ name: string;
+ description?: string;
+ images: MenuImage[];
+ price?: MenuPrice;
+ availability: MenuAvailability;
+ dietary: string[];
+ calories?: number;
+ optionGroups: unknown[];
+ identifiers: MenuItemIdentifiers;
+ url?: string;
+ sourceUrl: string;
+}
+
+export interface MenuSection {
+ id: string;
+ name: string;
+ description?: string;
+ items: MenuItem[];
+}
+
+export interface MenuMerchant {
+ name: string;
+ type?: string | null;
+ location?: unknown;
+}
+
+export interface MenuProfile {
+ isMenu: boolean;
+ confidence: number;
+ merchant: MenuMerchant;
+ currency?: string | null;
+ sections: MenuSection[];
+ sourceUrl: string;
+}
+
export interface DocumentMetadata {
// Common metadata fields
title?: string;
@@ -551,6 +609,7 @@ export interface Document {
changeTracking?: Record<string, unknown>;
branding?: BrandingProfile;
product?: ProductProfile;
+ menu?: MenuProfile;
}
// Pagination configuration for auto-fetching pages from v2 endpoints that return a `next` URL
diff --git a/apps/php-sdk/README.md b/apps/php-sdk/README.md
index 2b1bea1b9..09c912de7 100644
--- a/apps/php-sdk/README.md
+++ b/apps/php-sdk/README.md
@@ -98,6 +98,22 @@ $doc = $client->scrape('https://example.com/product', ScrapeOptions::with(
echo $doc->getProduct(); // Structured product data
```
+### Menu Extraction
+
+Use the `menu` format on restaurant or merchant menu pages for structured menu
+extraction (merchant profile plus ordered sections, each holding items with
+per-item price, availability, dietary tags, and images). It is the
+deterministic counterpart to the LLM-based `json` format, returned on the
+document's `getMenu()`.
+
+```php
+$doc = $client->scrape('https://example.com/menu', ScrapeOptions::with(
+ formats: ['menu'],
+));
+
+echo $doc->getMenu(); // Structured menu data
+```
+
### Video Extraction
Use the `video` format on supported video URLs, including YouTube and TikTok. The returned `video` field is a signed URL to the extracted video file.
@@ -114,7 +130,7 @@ echo $doc->getVideo();
Upload a local file (`html`, `pdf`, `docx`, etc.) via multipart form data and
parse it synchronously. Parse options intentionally exclude browser-only
-features such as change tracking, screenshot, branding, product, audio, video, actions,
+features such as change tracking, screenshot, branding, product, menu, audio, video, actions,
waitFor, location, and mobile. The `proxy` option only accepts `"auto"` or `"basic"`.
```php
diff --git a/apps/php-sdk/src/Models/Document.php b/apps/php-sdk/src/Models/Document.php
index 3a257c57a..d190ee106 100644
--- a/apps/php-sdk/src/Models/Document.php
+++ b/apps/php-sdk/src/Models/Document.php
@@ -35,6 +35,7 @@ final class Document
private readonly ?array $changeTracking = null,
private readonly ?array $branding = null,
private readonly ?Product $product = null,
+ private readonly ?Menu $menu = null,
) {}
/** @param array<string, mixed> $data */
@@ -62,6 +63,9 @@ final class Document
product: isset($data['product']) && is_array($data['product'])
? Product::fromArray($data['product'])
: null,
+ menu: isset($data['menu']) && is_array($data['menu'])
+ ? Menu::fromArray($data['menu'])
+ : null,
);
}
@@ -166,4 +170,9 @@ final class Document
{
return $this->product;
}
+
+ public function getMenu(): ?Menu
+ {
+ return $this->menu;
+ }
}
diff --git a/apps/php-sdk/src/Models/Menu.php b/apps/php-sdk/src/Models/Menu.php
new file mode 100644
index 000000000..b918a1da2
--- /dev/null
+++ b/apps/php-sdk/src/Models/Menu.php
@@ -0,0 +1,249 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Firecrawl\Models;
+
+/**
+ * Structured menu information extracted via the `menu` scrape format.
+ *
+ * Pricing, availability, and images live on individual items; the top-level
+ * menu carries the merchant profile and descriptive fields only. Sections and
+ * their items are inlined as associative arrays.
+ */
+final class Menu
+{
+ /**
+ * @param array<string, mixed> $merchant
+ * @param list<array<string, mixed>> $sections
+ */
+ public function __construct(
+ private readonly bool $isMenu,
+ private readonly float $confidence,
+ private readonly string $sourceUrl,
+ private readonly array $merchant = [],
+ private readonly ?string $currency = null,
+ private readonly array $sections = [],
+ ) {}
+
+ /** @param array<string, mixed> $data */
+ public static function fromArray(array $data): self
+ {
+ return new self(
+ isMenu: (bool) ($data['isMenu'] ?? false),
+ confidence: (float) ($data['confidence'] ?? 0),
+ sourceUrl: (string) ($data['sourceUrl'] ?? ''),
+ merchant: self::normalizeMerchant($data['merchant'] ?? null),
+ currency: ($data['currency'] ?? null) !== null ? (string) $data['currency'] : null,
+ sections: self::normalizeSections($data['sections'] ?? []),
+ );
+ }
+
+ /**
+ * @param mixed $merchant
+ * @return array<string, mixed>
+ */
+ private static function normalizeMerchant(mixed $merchant): array
+ {
+ if (!is_array($merchant)) {
+ return [];
+ }
+
+ $entry = ['name' => (string) ($merchant['name'] ?? '')];
+ if (array_key_exists('type', $merchant)) {
+ $entry['type'] = $merchant['type'] !== null ? (string) $merchant['type'] : null;
+ }
+ // Location is an arbitrary structure; pass it through untouched.
+ if (array_key_exists('location', $merchant)) {
+ $entry['location'] = $merchant['location'];
+ }
+
+ return $entry;
+ }
+
+ /**
+ * @param mixed $images
+ * @return list<array{url: string, alt?: string|null}>
+ */
+ private static function normalizeImages(mixed $images): array
+ {
+ if (!is_array($images)) {
+ return [];
+ }
+
+ $result = [];
+ foreach ($images as $image) {
+ if (!is_array($image) || !isset($image['url'])) {
+ continue;
+ }
+ $entry = ['url' => (string) $image['url']];
+ if (array_key_exists('alt', $image)) {
+ $entry['alt'] = $image['alt'] !== null ? (string) $image['alt'] : null;
+ }
+ $result[] = $entry;
+ }
+
+ return $result;
+ }
+
+ /**
+ * @param mixed $price
+ * @return array{amount: float, currency?: string|null, formatted?: string|null}|null
+ */
+ private static function normalizePrice(mixed $price): ?array
+ {
+ if (!is_array($price) || !isset($price['amount'])) {
+ return null;
+ }
+
+ $entry = ['amount' => (float) $price['amount']];
+ if (array_key_exists('currency', $price)) {
+ $entry['currency'] = $price['currency'] !== null ? (string) $price['currency'] : null;
+ }
+ if (array_key_exists('formatted', $price)) {
+ $entry['formatted'] = $price['formatted'] !== null ? (string) $price['formatted'] : null;
+ }
+
+ return $entry;
+ }
+
+ /**
+ * @param mixed $availability
+ * @return array{inStock: bool, text?: string|null}
+ */
+ private static function normalizeAvailability(mixed $availability): array
+ {
+ if (!is_array($availability)) {
+ return ['inStock' => false];
+ }
+
+ $entry = ['inStock' => (bool) ($availability['inStock'] ?? false)];
+ if (array_key_exists('text', $availability)) {
+ $entry['text'] = $availability['text'] !== null ? (string) $availability['text'] : null;
+ }
+
+ return $entry;
+ }
+
+ /**
+ * @param mixed $items
+ * @return list<array<string, mixed>>
+ */
+ private static function normalizeItems(mixed $items): array
+ {
+ if (!is_array($items)) {
+ return [];
+ }
+
+ $result = [];
+ foreach ($items as $item) {
+ if (!is_array($item)) {
+ continue;
+ }
+
+ $entry = [];
+ foreach (['id', 'name', 'description', 'url'] as $key) {
+ if (isset($item[$key])) {
+ $entry[$key] = (string) $item[$key];
+ }
+ }
+ // sourceUrl is always present on an item.
+ $entry['sourceUrl'] = (string) ($item['sourceUrl'] ?? '');
+ if (isset($item['images'])) {
+ $entry['images'] = self::normalizeImages($item['images']);
+ }
+ if (($price = self::normalizePrice($item['price'] ?? null)) !== null) {
+ $entry['price'] = $price;
+ }
+ // Availability is always present on an item.
+ $entry['availability'] = self::normalizeAvailability($item['availability'] ?? null);
+ if (isset($item['dietary']) && is_array($item['dietary'])) {
+ $entry['dietary'] = array_map(
+ static fn (mixed $d): string => (string) $d,
+ array_values($item['dietary']),
+ );
+ }
+ if (isset($item['calories'])) {
+ $entry['calories'] = (float) $item['calories'];
+ }
+ // optionGroups is an arbitrary structure; pass it through untouched.
+ if (isset($item['optionGroups']) && is_array($item['optionGroups'])) {
+ $entry['optionGroups'] = $item['optionGroups'];
+ }
+ if (
+ is_array($item['identifiers'] ?? null)
+ && isset($item['identifiers']['merchantItemId'])
+ ) {
+ $entry['identifiers'] = [
+ 'merchantItemId' => (string) $item['identifiers']['merchantItemId'],
+ ];
+ }
+
+ $result[] = $entry;
+ }
+
+ return $result;
+ }
+
+ /**
+ * @param mixed $sections
+ * @return list<array<string, mixed>>
+ */
+ private static function normalizeSections(mixed $sections): array
+ {
+ if (!is_array($sections)) {
+ return [];
+ }
+
+ $result = [];
+ foreach ($sections as $section) {
+ if (!is_array($section)) {
+ continue;
+ }
+
+ $entry = [];
+ foreach (['id', 'name', 'description'] as $key) {
+ if (isset($section[$key])) {
+ $entry[$key] = (string) $section[$key];
+ }
+ }
+ $entry['items'] = self::normalizeItems($section['items'] ?? []);
+
+ $result[] = $entry;
+ }
+
+ return $result;
+ }
+
+ public function getIsMenu(): bool
+ {
+ return $this->isMenu;
+ }
+
+ public function getConfidence(): float
+ {
+ return $this->confidence;
+ }
+
+ public function getSourceUrl(): string
+ {
+ return $this->sourceUrl;
+ }
+
+ /** @return array<string, mixed> */
+ public function getMerchant(): array
+ {
+ return $this->merchant;
+ }
+
+ public function getCurrency(): ?string
+ {
+ return $this->currency;
+ }
+
+ /** @return list<array<string, mixed>> */
+ public function getSections(): array
+ {
+ return $this->sections;
+ }
+}
diff --git a/apps/php-sdk/src/Models/ParseOptions.php b/apps/php-sdk/src/Models/ParseOptions.php
index 1377a2845..08db06878 100644
--- a/apps/php-sdk/src/Models/ParseOptions.php
+++ b/apps/php-sdk/src/Models/ParseOptions.php
@@ -10,7 +10,7 @@ use Firecrawl\Exceptions\FirecrawlException;
* Options for parsing uploaded files via `/v2/parse`.
*
* Parse does not support browser-rendering features (actions, waitFor,
- * location, mobile) nor the screenshot, branding, product, audio, video, or changeTracking formats.
+ * location, mobile) nor the screenshot, branding, product, menu, audio, video, or changeTracking formats.
* The proxy field only accepts "auto" or "basic".
*/
final class ParseOptions
@@ -21,6 +21,7 @@ final class ParseOptions
'screenshot@fullPage',
'branding',
'product',
+ 'menu',
'audio',
'video',
];
diff --git a/apps/php-sdk/tests/Unit/ModelsTest.php b/apps/php-sdk/tests/Unit/ModelsTest.php
index 221e2e372..0ffa3e577 100644
--- a/apps/php-sdk/tests/Unit/ModelsTest.php
+++ b/apps/php-sdk/tests/Unit/ModelsTest.php
@@ -5,6 +5,7 @@ declare(strict_types=1);
use Firecrawl\Models\CreditUsage;
use Firecrawl\Models\Document;
use Firecrawl\Models\Product;
+use Firecrawl\Models\Menu;
use Firecrawl\Models\MapData;
use Firecrawl\Models\BatchScrapeJob;
use Firecrawl\Models\CrawlJob;
@@ -166,6 +167,96 @@ it('returns null product when absent in Document', function (): void {
expect($doc->getProduct())->toBeNull();
});
+it('hydrates menu into Menu model in Document', function (): void {
+ $doc = Document::fromArray([
+ 'markdown' => '# Menu',
+ 'menu' => [
+ 'isMenu' => true,
+ 'confidence' => 0.95,
+ 'currency' => 'USD',
+ 'sourceUrl' => 'https://example.com/menu',
+ 'merchant' => [
+ 'name' => 'Cafe Acme',
+ 'type' => 'restaurant',
+ 'location' => ['city' => 'Springfield'],
+ ],
+ 'sections' => [
+ [
+ 'id' => 's1',
+ 'name' => 'Drinks',
+ 'description' => 'Hot and cold beverages.',
+ 'items' => [
+ [
+ 'id' => 'i1',
+ 'name' => 'Latte',
+ 'description' => 'Espresso with steamed milk.',
+ 'url' => 'https://example.com/menu/latte',
+ 'sourceUrl' => 'https://example.com/menu',
+ 'images' => [['url' => 'https://example.com/latte.jpg']],
+ 'price' => ['amount' => 4.5, 'currency' => 'USD', 'formatted' => '$4.50'],
+ 'availability' => ['inStock' => true, 'text' => 'Available'],
+ 'dietary' => ['vegetarian'],
+ 'calories' => 120,
+ 'optionGroups' => [['name' => 'Size', 'options' => ['S', 'M', 'L']]],
+ 'identifiers' => ['merchantItemId' => 'LATTE-1'],
+ ],
+ [
+ 'id' => 'i2',
+ 'name' => 'Water',
+ 'sourceUrl' => 'https://example.com/menu',
+ ],
+ ],
+ ],
+ ],
+ ],
+ ]);
+
+ $menu = $doc->getMenu();
+
+ expect($menu)->toBeInstanceOf(Menu::class);
+ expect($menu->getIsMenu())->toBeTrue();
+ expect($menu->getConfidence())->toBe(0.95);
+ expect($menu->getCurrency())->toBe('USD');
+ expect($menu->getSourceUrl())->toBe('https://example.com/menu');
+ expect($menu->getMerchant())->toBe([
+ 'name' => 'Cafe Acme',
+ 'type' => 'restaurant',
+ 'location' => ['city' => 'Springfield'],
+ ]);
+ expect($menu->getSections())->toHaveCount(1);
+
+ $section = $menu->getSections()[0];
+ expect($section['id'])->toBe('s1');
+ expect($section['name'])->toBe('Drinks');
+ expect($section['description'])->toBe('Hot and cold beverages.');
+ expect($section['items'])->toHaveCount(2);
+
+ $i1 = $section['items'][0];
+ expect($i1['id'])->toBe('i1');
+ expect($i1['name'])->toBe('Latte');
+ expect($i1['sourceUrl'])->toBe('https://example.com/menu');
+ expect($i1['images'])->toBe([['url' => 'https://example.com/latte.jpg']]);
+ expect($i1['price'])->toBe(['amount' => 4.5, 'currency' => 'USD', 'formatted' => '$4.50']);
+ expect($i1['availability'])->toBe(['inStock' => true, 'text' => 'Available']);
+ expect($i1['dietary'])->toBe(['vegetarian']);
+ expect($i1['calories'])->toBe(120.0);
+ expect($i1['optionGroups'])->toBe([['name' => 'Size', 'options' => ['S', 'M', 'L']]]);
+ expect($i1['identifiers'])->toBe(['merchantItemId' => 'LATTE-1']);
+
+ // Availability is always present, even when omitted from the payload.
+ $i2 = $section['items'][1];
+ expect($i2['name'])->toBe('Water');
+ expect($i2['availability'])->toBe(['inStock' => false]);
+ expect(array_key_exists('price', $i2))->toBeFalse();
+ expect(array_key_exists('calories', $i2))->toBeFalse();
+});
+
+it('returns null menu when absent in Document', function (): void {
+ $doc = Document::fromArray(['markdown' => '# No menu']);
+
+ expect($doc->getMenu())->toBeNull();
+});
+
it('coerces non-string scalar identity fields without a TypeError under strict_types', function (): void {
// Defensive: upstream data could carry a non-string scalar (e.g. a numeric
// brand). Under declare(strict_types=1) these must be cast, not passed raw.
diff --git a/apps/php-sdk/tests/Unit/ParseTest.php b/apps/php-sdk/tests/Unit/ParseTest.php
index 9fa6a6067..4c711ad83 100644
--- a/apps/php-sdk/tests/Unit/ParseTest.php
+++ b/apps/php-sdk/tests/Unit/ParseTest.php
@@ -49,6 +49,10 @@ it('rejects product parse format', function (): void {
ParseOptions::with(formats: ['product']);
})->throws(FirecrawlException::class);
+it('rejects menu parse format', function (): void {
+ ParseOptions::with(formats: ['menu']);
+})->throws(FirecrawlException::class);
+
it('rejects invalid proxy values', function (): void {
ParseOptions::with(proxy: 'stealth');
})->throws(FirecrawlException::class);
diff --git a/apps/python-sdk/README.md b/apps/python-sdk/README.md
index eb12cfb79..5c2a2e461 100644
--- a/apps/python-sdk/README.md
+++ b/apps/python-sdk/README.md
@@ -67,6 +67,15 @@ doc = firecrawl.scrape('https://firecrawl.dev', formats=['product'])
print(doc.product)
```
+### Menu extraction
+
+Use the `menu` format on menu pages to deterministically pull structured menu data (merchant, sections, items, prices, availability). It is the deterministic counterpart to the LLM-based `json` format.
+
+```python
+doc = firecrawl.scrape('https://example.com/restaurant/menu', formats=['menu'])
+print(doc.menu)
+```
+
### Parsing uploaded files
Use `parse` to upload local bytes/files (`html`, `pdf`, `docx`, etc.) as multipart form data and return the parsed document.
diff --git a/apps/python-sdk/firecrawl/__init__.py b/apps/python-sdk/firecrawl/__init__.py
index f2030b575..a49a6b663 100644
--- a/apps/python-sdk/firecrawl/__init__.py
+++ b/apps/python-sdk/firecrawl/__init__.py
@@ -17,7 +17,7 @@ from .v1 import (
V1ChangeTrackingOptions,
)
-__version__ = "4.30.1"
+__version__ = "4.30.2"
# Define the logger for the Firecrawl project
logger: logging.Logger = logging.getLogger("firecrawl")
diff --git a/apps/python-sdk/firecrawl/__tests__/unit/v2/methods/test_menu.py b/apps/python-sdk/firecrawl/__tests__/unit/v2/methods/test_menu.py
new file mode 100644
index 000000000..85c6df867
--- /dev/null
+++ b/apps/python-sdk/firecrawl/__tests__/unit/v2/methods/test_menu.py
@@ -0,0 +1,225 @@
+import pytest
+from unittest.mock import Mock
+from firecrawl.v2.methods.scrape import scrape
+from firecrawl.v2.types import ScrapeOptions
+
+
+class TestMenuFormat:
+ """Unit tests for menu format support."""
+
+ def test_scrape_with_menu_format_returns_menu_data(self):
+ """Test that scraping with menu format returns menu data."""
+ mock_response = Mock()
+ mock_response.ok = True
+ mock_response.json.return_value = {
+ "success": True,
+ "data": {
+ "markdown": "# Example Menu",
+ "menu": {
+ "isMenu": True,
+ "confidence": 0.95,
+ "currency": "USD",
+ "sourceUrl": "https://example.com/menu",
+ "merchant": {"name": "Acme Diner", "type": "restaurant"},
+ "sections": [
+ {
+ "id": "mains",
+ "name": "Mains",
+ "description": "Hearty plates",
+ "items": [
+ {
+ "id": "burger",
+ "name": "Classic Burger",
+ "description": "Beef patty with cheese",
+ "images": [{"url": "https://example.com/burger.jpg", "alt": "Burger"}],
+ "price": {"amount": 12.5, "currency": "USD", "formatted": "$12.50"},
+ "availability": {"inStock": True, "text": "Available"},
+ "dietary": ["contains-gluten"],
+ "calories": 800,
+ "optionGroups": [],
+ "identifiers": {"merchantItemId": "ITEM-1"},
+ "url": "https://example.com/menu#burger",
+ "sourceUrl": "https://example.com/menu",
+ }
+ ],
+ }
+ ],
+ }
+ }
+ }
+
+ mock_client = Mock()
+ mock_client.post.return_value = mock_response
+
+ result = scrape(mock_client, "https://example.com", ScrapeOptions(formats=["menu"]))
+
+ assert result.menu is not None
+ assert result.menu.is_menu is True
+ assert result.menu.confidence == 0.95
+ assert result.menu.currency == "USD"
+ assert result.menu.source_url == "https://example.com/menu"
+ assert result.menu.merchant.name == "Acme Diner"
+ assert result.menu.merchant.type == "restaurant"
+ section = result.menu.sections[0]
+ assert section.name == "Mains"
+ item = section.items[0]
+ assert item.name == "Classic Burger"
+ assert item.price.amount == 12.5
+ assert item.price.currency == "USD"
+ assert item.availability.in_stock is True
+ assert item.availability.text == "Available"
+ assert item.images[0].url == "https://example.com/burger.jpg"
+ assert item.dietary[0] == "contains-gluten"
+ assert item.calories == 800
+ assert item.identifiers.merchant_item_id == "ITEM-1"
+ assert item.source_url == "https://example.com/menu"
+
+ def test_scrape_with_menu_and_markdown_formats_returns_both(self):
+ """Test that scraping with both menu and markdown formats returns both."""
+ mock_response = Mock()
+ mock_response.ok = True
+ mock_response.json.return_value = {
+ "success": True,
+ "data": {
+ "markdown": "# Example Content",
+ "menu": {
+ "isMenu": True,
+ "confidence": 0.8,
+ "sourceUrl": "https://example.com/cafe",
+ "merchant": {"name": "Cafe Acme"},
+ "sections": [
+ {
+ "id": "drinks",
+ "name": "Drinks",
+ "items": [
+ {
+ "id": "coffee",
+ "name": "Coffee",
+ "images": [],
+ "price": {"amount": 3.5, "currency": "USD"},
+ "availability": {"inStock": True},
+ "dietary": [],
+ "optionGroups": [],
+ "identifiers": {},
+ "sourceUrl": "https://example.com/cafe",
+ }
+ ],
+ }
+ ],
+ }
+ }
+ }
+
+ mock_client = Mock()
+ mock_client.post.return_value = mock_response
+
+ result = scrape(mock_client, "https://example.com", ScrapeOptions(formats=["markdown", "menu"]))
+
+ assert result.markdown == "# Example Content"
+ assert result.menu is not None
+ assert result.menu.merchant.name == "Cafe Acme"
+ assert result.menu.sections[0].items[0].price.amount == 3.5
+
+ def test_scrape_without_menu_format_does_not_return_menu(self):
+ """Test that scraping without menu format does not return menu."""
+ mock_response = Mock()
+ mock_response.ok = True
+ mock_response.json.return_value = {
+ "success": True,
+ "data": {
+ "markdown": "# Example"
+ }
+ }
+
+ mock_client = Mock()
+ mock_client.post.return_value = mock_response
+
+ result = scrape(mock_client, "https://example.com", ScrapeOptions(formats=["markdown"]))
+
+ assert result.markdown == "# Example"
+ assert result.menu is None
+
+ def test_non_menu_page_yields_warning_and_no_menu(self):
+ """Test that a non-menu page scraped with menu format yields a warning and no menu."""
+ mock_response = Mock()
+ mock_response.ok = True
+ mock_response.json.return_value = {
+ "success": True,
+ "data": {
+ "markdown": "# Blog Post",
+ "warning": "No menu found on this page."
+ }
+ }
+
+ mock_client = Mock()
+ mock_client.post.return_value = mock_response
+
+ result = scrape(mock_client, "https://example.com", ScrapeOptions(formats=["menu"]))
+
+ assert result.menu is None
+ assert "No menu found" in result.warning
+
+ def test_menu_format_with_multiple_sections_and_items(self):
+ """Test menu format with multiple sections and items, including camelCase aliasing."""
+ mock_response = Mock()
+ mock_response.ok = True
+ mock_response.json.return_value = {
+ "success": True,
+ "data": {
+ "menu": {
+ "isMenu": True,
+ "confidence": 0.9,
+ "sourceUrl": "https://example.com/menu",
+ "merchant": {"name": "Acme Bistro", "type": "restaurant", "location": {"city": "Springfield"}},
+ "sections": [
+ {
+ "id": "starters",
+ "name": "Starters",
+ "items": [
+ {
+ "id": "soup",
+ "name": "Tomato Soup",
+ "images": [],
+ "price": {"amount": 6.0, "currency": "USD"},
+ "availability": {"inStock": True},
+ "dietary": ["vegetarian"],
+ "optionGroups": [],
+ "identifiers": {},
+ "sourceUrl": "https://example.com/menu",
+ }
+ ],
+ },
+ {
+ "id": "desserts",
+ "name": "Desserts",
+ "items": [
+ {
+ "id": "cake",
+ "name": "Chocolate Cake",
+ "images": [{"url": "https://example.com/cake.jpg"}],
+ "availability": {"inStock": False, "text": "Sold out"},
+ "dietary": [],
+ "optionGroups": [],
+ "identifiers": {},
+ "sourceUrl": "https://example.com/menu",
+ }
+ ],
+ },
+ ],
+ }
+ }
+ }
+
+ mock_client = Mock()
+ mock_client.post.return_value = mock_response
+
+ result = scrape(mock_client, "https://example.com", ScrapeOptions(formats=["menu"]))
+
+ assert result.menu is not None
+ assert len(result.menu.sections) == 2
+ assert result.menu.merchant.location == {"city": "Springfield"}
+ assert result.menu.sections[0].items[0].dietary[0] == "vegetarian"
+ assert result.menu.sections[1].name == "Desserts"
+ assert result.menu.sections[1].items[0].images[0].url == "https://example.com/cake.jpg"
+ assert result.menu.sections[1].items[0].availability.in_stock is False
+ assert result.menu.sections[1].items[0].availability.text == "Sold out"
diff --git a/apps/python-sdk/firecrawl/v2/types.py b/apps/python-sdk/firecrawl/v2/types.py
index 742a2f68e..9347e7d6b 100644
--- a/apps/python-sdk/firecrawl/v2/types.py
+++ b/apps/python-sdk/firecrawl/v2/types.py
@@ -326,6 +326,95 @@ class ProductProfile(BaseModel):
variants: List[ProductVariant] = Field(default_factory=list)
+class MenuPrice(BaseModel):
+ """A monetary price for a menu item."""
+
+ model_config = {"extra": "allow", "populate_by_name": True}
+
+ amount: float
+ currency: Optional[str] = None
+ formatted: Optional[str] = None
+
+
+class MenuAvailability(BaseModel):
+ """Availability information for a menu item."""
+
+ model_config = {"extra": "allow", "populate_by_name": True}
+
+ in_stock: bool = Field(alias="inStock")
+ text: Optional[str] = None
+
+
+class MenuImage(BaseModel):
+ """An image associated with a menu item."""
+
+ model_config = {"extra": "allow", "populate_by_name": True}
+
+ url: str
+ alt: Optional[str] = None
+
+
+class MenuItemIdentifiers(BaseModel):
+ """External identifiers for a menu item."""
+
+ model_config = {"extra": "allow", "populate_by_name": True}
+
+ merchant_item_id: Optional[str] = Field(default=None, alias="merchantItemId")
+
+
+class MenuItem(BaseModel):
+ """A single item on a menu."""
+
+ model_config = {"extra": "allow", "populate_by_name": True}
+
+ id: str
+ name: str
+ description: Optional[str] = None
+ images: List[MenuImage] = Field(default_factory=list)
+ price: Optional[MenuPrice] = None
+ availability: MenuAvailability
+ dietary: List[str] = Field(default_factory=list)
+ calories: Optional[float] = None
+ option_groups: List[Any] = Field(default_factory=list, alias="optionGroups")
+ identifiers: MenuItemIdentifiers = Field(default_factory=MenuItemIdentifiers)
+ url: Optional[str] = None
+ source_url: str = Field(alias="sourceUrl")
+
+
+class MenuSection(BaseModel):
+ """An ordered group of menu items."""
+
+ model_config = {"extra": "allow", "populate_by_name": True}
+
+ id: str
+ name: str
+ description: Optional[str] = None
+ items: List[MenuItem] = Field(default_factory=list)
+
+
+class MenuMerchant(BaseModel):
+ """The merchant a menu belongs to."""
+
+ model_config = {"extra": "allow", "populate_by_name": True}
+
+ name: str
+ type: Optional[str] = None
+ location: Optional[Any] = None
+
+
+class MenuProfile(BaseModel):
+ """Structured menu information extracted from a website."""
+
+ model_config = {"extra": "allow", "populate_by_name": True}
+
+ is_menu: bool = Field(alias="isMenu")
+ confidence: float
+ merchant: MenuMerchant
+ currency: Optional[str] = None
+ sections: List[MenuSection] = Field(default_factory=list)
+ source_url: str = Field(alias="sourceUrl")
+
+
RedactPIIEntity = Literal[
"PERSON",
"EMAIL",
@@ -357,6 +446,7 @@ class Document(BaseModel):
change_tracking: Optional[Dict[str, Any]] = None
branding: Optional[BrandingProfile] = None
product: Optional[ProductProfile] = None
+ menu: Optional[MenuProfile] = None
@property
def metadata_typed(self) -> DocumentMetadata:
@@ -481,6 +571,7 @@ FormatString = Literal[
"attributes",
"branding",
"product",
+ "menu",
"query",
"audio",
"video",
diff --git a/apps/ruby-sdk/README.md b/apps/ruby-sdk/README.md
index 6b8876b05..c83a21d19 100644
--- a/apps/ruby-sdk/README.md
+++ b/apps/ruby-sdk/README.md
@@ -88,6 +88,21 @@ doc = client.scrape("https://example.com/products/widget",
puts doc.product
```
+### Menu Extraction
+
+Use the `menu` format on restaurant/merchant menu pages to get structured
+menu data (merchant profile plus ordered sections, each holding items with
+per-item price, availability, images, and dietary information). It is the
+deterministic counterpart to the LLM-based `json` format. The returned `menu`
+field contains the extracted fields.
+
+```ruby
+doc = client.scrape("https://example.com/menu",
+ Firecrawl::Models::ScrapeOptions.new(formats: ["menu"]))
+
+puts doc.menu
+```
+
### Parse
Upload a local file (`html`, `pdf`, `docx`, etc.) via multipart form data and
diff --git a/apps/ruby-sdk/lib/firecrawl.rb b/apps/ruby-sdk/lib/firecrawl.rb
index 101d23d24..6514a2182 100644
--- a/apps/ruby-sdk/lib/firecrawl.rb
+++ b/apps/ruby-sdk/lib/firecrawl.rb
@@ -5,6 +5,7 @@ require_relative "firecrawl/errors"
require_relative "firecrawl/http_client"
require_relative "firecrawl/models/query_format"
require_relative "firecrawl/models/product_profile"
+require_relative "firecrawl/models/menu_profile"
require_relative "firecrawl/models/document"
require_relative "firecrawl/models/scrape_options"
require_relative "firecrawl/models/crawl_options"
diff --git a/apps/ruby-sdk/lib/firecrawl/models/document.rb b/apps/ruby-sdk/lib/firecrawl/models/document.rb
index 00f2d38f7..b13c9cebe 100644
--- a/apps/ruby-sdk/lib/firecrawl/models/document.rb
+++ b/apps/ruby-sdk/lib/firecrawl/models/document.rb
@@ -7,7 +7,7 @@ module Firecrawl
attr_reader :markdown, :html, :raw_html, :json, :summary,
:metadata, :links, :images, :screenshot, :audio,
:video, :attributes, :actions, :answer, :highlights,
- :warning, :change_tracking, :branding, :product
+ :warning, :change_tracking, :branding, :product, :menu
def initialize(data)
@markdown = data["markdown"]
@@ -29,6 +29,7 @@ module Firecrawl
@change_tracking = data["changeTracking"]
@branding = data["branding"]
@product = data["product"] && ProductProfile.new(data["product"])
+ @menu = data["menu"] && MenuProfile.new(data["menu"])
end
def to_s
diff --git a/apps/ruby-sdk/lib/firecrawl/models/menu_profile.rb b/apps/ruby-sdk/lib/firecrawl/models/menu_profile.rb
new file mode 100644
index 000000000..eb3196d0c
--- /dev/null
+++ b/apps/ruby-sdk/lib/firecrawl/models/menu_profile.rb
@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module Firecrawl
+ module Models
+ # Structured menu information extracted from a restaurant/merchant page
+ # via the `menu` scrape format.
+ class MenuProfile
+ # An image associated with a menu item.
+ class Image
+ attr_reader :url, :alt
+
+ def initialize(data)
+ @url = data["url"]
+ @alt = data["alt"]
+ end
+ end
+
+ # A monetary value with an optional currency and formatted string.
+ class Price
+ attr_reader :amount, :currency, :formatted
+
+ def initialize(data)
+ @amount = data["amount"]
+ @currency = data["currency"]
+ @formatted = data["formatted"]
+ end
+ end
+
+ # Stock availability information for a menu item. Always present.
+ class Availability
+ attr_reader :in_stock, :text
+
+ def initialize(data)
+ data ||= {}
+ @in_stock = data["inStock"] || false
+ @text = data["text"]
+ end
+ end
+
+ # Merchant (restaurant/business) profile for the menu.
+ class Merchant
+ attr_reader :name, :type, :location
+
+ def initialize(data)
+ data ||= {}
+ @name = data["name"]
+ @type = data["type"]
+ @location = data["location"]
+ end
+ end
+
+ # Identifiers carried on a menu item.
+ class Identifiers
+ attr_reader :merchant_item_id
+
+ def initialize(data)
+ data ||= {}
+ @merchant_item_id = data["merchantItemId"]
+ end
+ end
+
+ # A single item on the menu. Pricing, availability, images, and dietary
+ # information live here rather than on the section or profile.
+ class Item
+ attr_reader :id, :name, :description, :images, :price, :availability,
+ :dietary, :calories, :option_groups, :identifiers, :url,
+ :source_url
+
+ def initialize(data)
+ @id = data["id"]
+ @name = data["name"]
+ @description = data["description"]
+ @images = (data["images"] || []).map { |img| Image.new(img) }
+ @price = data["price"] && Price.new(data["price"])
+ @availability = Availability.new(data["availability"])
+ @dietary = data["dietary"] || []
+ @calories = data["calories"]
+ @option_groups = data["optionGroups"] || []
+ @identifiers = Identifiers.new(data["identifiers"])
+ @url = data["url"]
+ @source_url = data["sourceUrl"]
+ end
+ end
+
+ # An ordered group of menu items.
+ class Section
+ attr_reader :id, :name, :description, :items
+
+ def initialize(data)
+ @id = data["id"]
+ @name = data["name"]
+ @description = data["description"]
+ @items = (data["items"] || []).map { |item| Item.new(item) }
+ end
+ end
+
+ attr_reader :is_menu, :confidence, :merchant, :currency, :sections,
+ :source_url
+
+ def initialize(data)
+ @is_menu = data["isMenu"] || false
+ @confidence = data["confidence"]
+ @merchant = Merchant.new(data["merchant"])
+ @currency = data["currency"]
+ @sections = (data["sections"] || []).map { |section| Section.new(section) }
+ @source_url = data["sourceUrl"]
+ end
+
+ def to_s
+ "MenuProfile{merchant=#{merchant&.name || 'unknown'}, sourceUrl=#{source_url || 'unknown'}}"
+ end
+ end
+ end
+end
diff --git a/apps/ruby-sdk/lib/firecrawl/models/parse_options.rb b/apps/ruby-sdk/lib/firecrawl/models/parse_options.rb
index ca2c4f874..b29d4fa04 100644
--- a/apps/ruby-sdk/lib/firecrawl/models/parse_options.rb
+++ b/apps/ruby-sdk/lib/firecrawl/models/parse_options.rb
@@ -5,10 +5,10 @@ module Firecrawl
# Options for parsing uploaded files via `/v2/parse`.
#
# Parse does not support browser-rendering features (actions, waitFor,
- # location, mobile) nor screenshot/branding/product/audio/video/changeTracking formats. The
+ # location, mobile) nor screenshot/branding/product/menu/audio/video/changeTracking formats. The
# proxy field only accepts "auto" or "basic".
class ParseOptions
- UNSUPPORTED_FORMATS = %w[changeTracking screenshot screenshot@fullPage branding product audio video].freeze
+ UNSUPPORTED_FORMATS = %w[changeTracking screenshot screenshot@fullPage branding product menu audio video].freeze
FIELDS = %i[
formats headers include_tags exclude_tags only_main_content
diff --git a/apps/ruby-sdk/lib/firecrawl/version.rb b/apps/ruby-sdk/lib/firecrawl/version.rb
index e762a2a78..a373ae836 100644
--- a/apps/ruby-sdk/lib/firecrawl/version.rb
+++ b/apps/ruby-sdk/lib/firecrawl/version.rb
@@ -1,5 +1,5 @@
# frozen_string_literal: true
module Firecrawl
- VERSION = "1.9.1"
+ VERSION = "1.9.2"
end
diff --git a/apps/ruby-sdk/test/firecrawl/client_test.rb b/apps/ruby-sdk/test/firecrawl/client_test.rb
index c2ca91934..840506716 100644
--- a/apps/ruby-sdk/test/firecrawl/client_test.rb
+++ b/apps/ruby-sdk/test/firecrawl/client_test.rb
@@ -191,6 +191,124 @@ class ClientTest < Minitest::Test
assert_nil doc.product
end
+ def test_scrape_with_menu_format
+ stub_request(:post, "#{BASE_URL}/v2/scrape")
+ .to_return(
+ status: 200,
+ body: JSON.generate(
+ data: {
+ markdown: "# Menu",
+ menu: {
+ isMenu: true,
+ confidence: 0.92,
+ currency: "USD",
+ sourceUrl: "https://example.com/menu",
+ merchant: {
+ name: "Joe's Diner",
+ type: "restaurant",
+ location: { city: "Springfield" },
+ },
+ sections: [
+ {
+ id: "s1",
+ name: "Breakfast",
+ description: "Served all day.",
+ items: [
+ {
+ id: "i1",
+ name: "Pancakes",
+ description: "Fluffy stack.",
+ images: [{ url: "https://example.com/pancakes.jpg", alt: "Pancakes" }],
+ price: { amount: 899, currency: "USD", formatted: "$8.99" },
+ availability: { inStock: true, text: "Available" },
+ dietary: ["vegetarian"],
+ calories: 520,
+ optionGroups: [{ name: "Syrup" }],
+ identifiers: { merchantItemId: "MENU-1" },
+ url: "https://example.com/menu#pancakes",
+ sourceUrl: "https://example.com/menu",
+ },
+ {
+ id: "i2",
+ name: "Toast",
+ sourceUrl: "https://example.com/menu",
+ },
+ ],
+ },
+ ],
+ },
+ }
+ ),
+ headers: { "Content-Type" => "application/json" }
+ )
+
+ doc = @client.scrape("https://example.com/menu")
+ menu = doc.menu
+ assert_instance_of Firecrawl::Models::MenuProfile, menu
+ assert_equal true, menu.is_menu
+ assert_in_delta 0.92, menu.confidence, 0.0001
+ assert_equal "USD", menu.currency
+ assert_equal "https://example.com/menu", menu.source_url
+
+ assert_equal "Joe's Diner", menu.merchant.name
+ assert_equal "restaurant", menu.merchant.type
+ assert_equal({ "city" => "Springfield" }, menu.merchant.location)
+
+ assert_equal 1, menu.sections.size
+ section = menu.sections.first
+ assert_equal "s1", section.id
+ assert_equal "Breakfast", section.name
+ assert_equal "Served all day.", section.description
+
+ assert_equal 2, section.items.size
+ item = section.items.first
+ assert_equal "i1", item.id
+ assert_equal "Pancakes", item.name
+ assert_equal "Fluffy stack.", item.description
+
+ assert_equal 1, item.images.size
+ assert_equal "https://example.com/pancakes.jpg", item.images.first.url
+ assert_equal "Pancakes", item.images.first.alt
+
+ assert_equal 899, item.price.amount
+ assert_equal "USD", item.price.currency
+ assert_equal "$8.99", item.price.formatted
+
+ assert_equal true, item.availability.in_stock
+ assert_equal "Available", item.availability.text
+
+ assert_equal ["vegetarian"], item.dietary
+ assert_equal 520, item.calories
+ assert_equal [{ "name" => "Syrup" }], item.option_groups
+ assert_equal "MENU-1", item.identifiers.merchant_item_id
+ assert_equal "https://example.com/menu#pancakes", item.url
+ assert_equal "https://example.com/menu", item.source_url
+
+ # price/images/calories optional; availability always present.
+ bare = section.items.last
+ assert_equal "i2", bare.id
+ assert_nil bare.price
+ assert_nil bare.calories
+ assert_empty bare.images
+ assert_empty bare.dietary
+ assert_empty bare.option_groups
+ refute_nil bare.availability
+ assert_equal false, bare.availability.in_stock
+ assert_nil bare.identifiers.merchant_item_id
+ end
+
+ def test_scrape_without_menu_format_leaves_menu_nil
+ stub_request(:post, "#{BASE_URL}/v2/scrape")
+ .to_return(
+ status: 200,
+ body: JSON.generate(data: { markdown: "# Hi" }),
+ headers: { "Content-Type" => "application/json" }
+ )
+
+ doc = @client.scrape("https://example.com")
+ assert_nil doc.menu
+ end
+
# ================================================================
# CRAWL
# ================================================================
@@ -781,6 +899,12 @@ class ClientTest < Minitest::Test
end
end
+ def test_parse_options_rejects_menu_format
+ assert_raises(ArgumentError) do
+ Firecrawl::Models::ParseOptions.new(formats: ["menu"])
+ end
+ end
+
def test_parse_options_rejects_invalid_proxy
assert_raises(ArgumentError) do
Firecrawl::Models::ParseOptions.new(proxy: "stealth")
diff --git a/apps/rust-sdk/Cargo.lock b/apps/rust-sdk/Cargo.lock
index a78b1a047..5fd1cde86 100644
--- a/apps/rust-sdk/Cargo.lock
+++ b/apps/rust-sdk/Cargo.lock
@@ -250,7 +250,7 @@ checksum = "37909eebbb50d72f9059c3b6d82c0463f2ff062c9e95845c43a6c9c0355411be"
[[package]]
name = "firecrawl"
-version = "2.9.1"
+version = "2.10.0"
dependencies = [
"mockito",
"reqwest",
diff --git a/apps/rust-sdk/Cargo.toml b/apps/rust-sdk/Cargo.toml
index fbb6b9a87..d8f9163f5 100644
--- a/apps/rust-sdk/Cargo.toml
+++ b/apps/rust-sdk/Cargo.toml
@@ -1,6 +1,6 @@
[package]
name = "firecrawl"
-version = "2.9.1"
+version = "2.10.0"
edition = "2021"
license = "MIT"
homepage = "https://www.firecrawl.dev/"
diff --git a/apps/rust-sdk/README.md b/apps/rust-sdk/README.md
index 023c108a7..e2e437b41 100644
--- a/apps/rust-sdk/README.md
+++ b/apps/rust-sdk/README.md
@@ -76,6 +76,24 @@ let doc = client
println!("{:?}", doc.product);
```
+### Menu extraction
+
+Use `Format::Menu` on restaurant/menu pages for structured menu extraction (merchant, sections, items, prices, availability). The result is returned on the document's `menu` field. This is the deterministic counterpart to the LLM-based `json` format.
+
+```rust
+use firecrawl::{Format, ScrapeOptions};
+
+let options = ScrapeOptions {
+ formats: Some(vec![Format::Menu]),
+ ..Default::default()
+};
+
+let doc = client
+ .scrape("https://www.example.com/menu", options)
+ .await?;
+println!("{:?}", doc.menu);
+```
+
### Parsing uploaded files (v2)
Use the v2 client `parse` method to upload local files (`html`, `pdf`, `docx`, etc.) as multipart form data.
diff --git a/apps/rust-sdk/src/types.rs b/apps/rust-sdk/src/types.rs
index acf42854a..b97b4036d 100644
--- a/apps/rust-sdk/src/types.rs
+++ b/apps/rust-sdk/src/types.rs
@@ -33,6 +33,8 @@ pub enum Format {
Branding,
/// Product extraction from the page.
Product,
+ /// Menu extraction from the page.
+ Menu,
/// Audio extraction (MP3) from YouTube videos.
Audio,
/// Video extraction from supported video URLs.
@@ -63,6 +65,7 @@ impl Serialize for Format {
Format::Attributes => serializer.serialize_str("attributes"),
Format::Branding => serializer.serialize_str("branding"),
Format::Product => serializer.serialize_str("product"),
+ Format::Menu => serializer.serialize_str("menu"),
Format::Audio => serializer.serialize_str("audio"),
Format::Video => serializer.serialize_str("video"),
Format::Question(question) => question.serialize(serializer),
@@ -92,6 +95,7 @@ impl<'de> Deserialize<'de> for Format {
"attributes" => Ok(Format::Attributes),
"branding" => Ok(Format::Branding),
"product" => Ok(Format::Product),
+ "menu" => Ok(Format::Menu),
"audio" => Ok(Format::Audio),
"video" => Ok(Format::Video),
_ => Err(de::Error::custom(format!("unknown format: {}", format))),
@@ -684,6 +688,8 @@ pub struct Document {
pub branding: Option<Value>,
/// Product extraction result.
pub product: Option<Product>,
+ /// Menu extraction result.
+ pub menu: Option<Menu>,
}
/// Product extraction result for a page.
@@ -774,6 +780,136 @@ pub struct ProductSale {
pub original_price: ProductPrice,
}
+/// Menu extraction result for a page.
+#[serde_with::skip_serializing_none]
+#[derive(Deserialize, Serialize, Debug, Default, Clone)]
+#[serde(rename_all = "camelCase")]
+pub struct Menu {
+ /// Whether the page was identified as a menu.
+ pub is_menu: bool,
+ /// Confidence score for the menu classification.
+ pub confidence: f64,
+ /// Currency code for the menu prices.
+ pub currency: Option<String>,
+ /// Source URL of the menu.
+ pub source_url: String,
+ /// Merchant information.
+ pub merchant: MenuMerchant,
+ /// Menu sections.
+ #[serde(default)]
+ pub sections: Vec<MenuSection>,
+}
+
+/// Merchant information for a menu.
+#[serde_with::skip_serializing_none]
+#[derive(Deserialize, Serialize, Debug, Default, Clone)]
+#[serde(rename_all = "camelCase")]
+pub struct MenuMerchant {
+ /// Merchant name.
+ pub name: String,
+ /// Merchant type.
+ #[serde(rename = "type")]
+ pub merchant_type: Option<String>,
+ /// Merchant location (arbitrary shape).
+ pub location: Option<Value>,
+}
+
+/// A section of a menu.
+#[serde_with::skip_serializing_none]
+#[derive(Deserialize, Serialize, Debug, Default, Clone)]
+#[serde(rename_all = "camelCase")]
+pub struct MenuSection {
+ /// Section identifier.
+ pub id: String,
+ /// Section name.
+ pub name: String,
+ /// Section description.
+ pub description: Option<String>,
+ /// Items in the section.
+ #[serde(default)]
+ pub items: Vec<MenuItem>,
+}
+
+/// An item on a menu.
+#[serde_with::skip_serializing_none]
+#[derive(Deserialize, Serialize, Debug, Default, Clone)]
+#[serde(rename_all = "camelCase")]
+pub struct MenuItem {
+ /// Item identifier.
+ pub id: String,
+ /// Item name.
+ pub name: String,
+ /// Item description.
+ pub description: Option<String>,
+ /// Item images.
+ #[serde(default)]
+ pub images: Vec<MenuImage>,
+ /// Item price.
+ pub price: Option<MenuPrice>,
+ /// Item availability information.
+ pub availability: MenuAvailability,
+ /// Dietary tags.
+ #[serde(default)]
+ pub dietary: Vec<String>,
+ /// Calorie count.
+ pub calories: Option<f64>,
+ /// Option groups (arbitrary shape).
+ #[serde(default)]
+ pub option_groups: Vec<Value>,
+ /// Item identifiers.
+ #[serde(default)]
+ pub identifiers: MenuItemIdentifiers,
+ /// Item URL.
+ pub url: Option<String>,
+ /// Source URL of the item.
+ pub source_url: String,
+}
+
+/// An image associated with a menu item.
+#[serde_with::skip_serializing_none]
+#[derive(Deserialize, Serialize, Debug, Default, Clone)]
+#[serde(rename_all = "camelCase")]
+pub struct MenuImage {
+ /// Image URL.
+ pub url: String,
+ /// Alternative text for the image.
+ pub alt: Option<String>,
+}
+
+/// Price information for a menu item.
+#[serde_with::skip_serializing_none]
+#[derive(Deserialize, Serialize, Debug, Default, Clone)]
+#[serde(rename_all = "camelCase")]
+pub struct MenuPrice {
+ /// Numeric price amount.
+ pub amount: f64,
+ /// Currency code.
+ pub currency: Option<String>,
+ /// Human-readable formatted price.
+ pub formatted: Option<String>,
+}
+
+/// Availability information for a menu item.
+#[serde_with::skip_serializing_none]
+#[derive(Deserialize, Serialize, Debug, Default, Clone)]
+#[serde(rename_all = "camelCase")]
+pub struct MenuAvailability {
+ /// Whether the item is in stock.
+ #[serde(rename = "inStock")]
+ pub in_stock: bool,
+ /// Human-readable availability text.
+ pub text: Option<String>,
+}
+
+/// Identifiers for a menu item.
+#[serde_with::skip_serializing_none]
+#[derive(Deserialize, Serialize, Debug, Default, Clone)]
+#[serde(rename_all = "camelCase")]
+pub struct MenuItemIdentifiers {
+ /// Merchant-specific item identifier.
+ pub merchant_item_id: Option<String>,
+}
+
/// Job status types for crawl and batch operations.
#[derive(Deserialize, Serialize, Clone, Copy, Debug, PartialEq, Eq)]
#[serde(rename_all = "camelCase")]
@@ -922,4 +1058,78 @@ mod tests {
assert_eq!(meta.language, Some("en".to_string()));
assert_eq!(meta.keywords, Some("rust, sdk, firecrawl".to_string()));
}
+
+ #[test]
+ fn test_format_menu_round_trip() {
+ let format = Format::Menu;
+ let serialized = serde_json::to_value(&format).unwrap();
+ assert_eq!(serialized, json!("menu"));
+ let deserialized: Format = serde_json::from_value(json!("menu")).unwrap();
+ assert_eq!(deserialized, Format::Menu);
+ }
+
+ #[test]
+ fn test_document_with_menu() {
+ let json = json!({
+ "menu": {
+ "isMenu": true,
+ "confidence": 0.95,
+ "currency": "USD",
+ "sourceUrl": "https://example.com/menu",
+ "merchant": {
+ "name": "Test Diner",
+ "type": "restaurant",
+ "location": { "city": "Springfield" }
+ },
+ "sections": [
+ {
+ "id": "s1",
+ "name": "Mains",
+ "items": [
+ {
+ "id": "i1",
+ "name": "Burger",
+ "images": [{ "url": "https://example.com/burger.jpg" }],
+ "price": { "amount": 12.5, "currency": "USD", "formatted": "$12.50" },
+ "availability": { "inStock": true },
+ "dietary": ["vegetarian"],
+ "optionGroups": [],
+ "identifiers": { "merchantItemId": "abc123" },
+ "sourceUrl": "https://example.com/menu#i1"
+ }
+ ]
+ }
+ ]
+ }
+ });
+ let doc: Document = serde_json::from_value(json).unwrap();
+ let menu = doc.menu.as_ref().expect("menu should be present");
+ assert!(menu.is_menu);
+ assert_eq!(menu.confidence, 0.95);
+ assert_eq!(menu.currency, Some("USD".to_string()));
+ assert_eq!(menu.source_url, "https://example.com/menu");
+ assert_eq!(menu.merchant.name, "Test Diner");
+ assert_eq!(menu.merchant.merchant_type, Some("restaurant".to_string()));
+ assert_eq!(menu.sections.len(), 1);
+ let section = &menu.sections[0];
+ assert_eq!(section.name, "Mains");
+ assert_eq!(section.items.len(), 1);
+ let item = &section.items[0];
+ assert_eq!(item.name, "Burger");
+ assert!(item.availability.in_stock);
+ assert_eq!(item.dietary, vec!["vegetarian".to_string()]);
+ assert_eq!(
+ item.identifiers.merchant_item_id,
+ Some("abc123".to_string())
+ );
+ let price = item.price.as_ref().unwrap();
+ assert_eq!(price.amount, 12.5);
+
+ // Round-trip back to JSON and ensure camelCase field names are preserved.
+ let reserialized = serde_json::to_value(&doc).unwrap();
+ let item_json = &reserialized["menu"]["sections"][0]["items"][0];
+ assert_eq!(item_json["sourceUrl"], "https://example.com/menu#i1");
+ assert_eq!(item_json["availability"]["inStock"], true);
+ assert_eq!(item_json["identifiers"]["merchantItemId"], "abc123");
+ }
}