diff --git a/FMARKETPLACE.md b/FMARKETPLACE.md new file mode 100644 index 0000000..c7e86ab --- /dev/null +++ b/FMARKETPLACE.md @@ -0,0 +1,382 @@ +# Facebook Marketplace API Reverse Engineering + +## Overview +This document tracks findings from reverse-engineering Facebook Marketplace APIs for listing details. + +## Current Implementation Status +- Search functionality: Implemented in `src/facebook.ts` +- Individual listing details: Not yet implemented + +## Findings + +### Step 1: Initial Setup +- Using Chrome DevTools to inspect Facebook Marketplace +- Need to authenticate with Facebook account to access marketplace data +- Cookies required for full access +- Current status: Successfully logged in and accessed marketplace data + +### Step 2: Individual Listing Details Analysis - COMPLETED +- **Data Location**: Embedded in HTML script tags within `require` array structure +- **Path**: `require[0][3].__bbox.result.data.viewer.marketplace_product_details_page.target` +- **Authentication**: Required for full data access +- **Current Status**: Successfully reverse-engineered the API structure and data extraction method + +### API Endpoints Discovered + +#### Search Endpoint +- URL: `https://www.facebook.com/marketplace/{location}/search` +- Parameters: `query`, `sortBy`, `exact` +- Data embedded in HTML script tags with `require` structure +- Authentication: Required (cookies) + +#### Listing Details Endpoint +- **URL Structure**: `https://www.facebook.com/marketplace/item/{listing_id}/` +- **Data Source**: Server-side rendered HTML with embedded JSON data in script tags +- **Data Structure**: Relay/GraphQL style data structure under `require[0][3].__bbox.require[...].__bbox.result.data.viewer.marketplace_product_details_page.target` +- **Extraction Method**: Parse JSON from script tags containing marketplace data, navigate to the target object +- **Authentication**: Required (cookies) + +### Listing Data Structure Discovered (Current - 2026) + +The current Facebook Marketplace API returns a comprehensive `GroupCommerceProductItem` object with the following key properties: + +```typescript +interface FacebookMarketplaceItem { + // Basic identification + id: string; + __typename: "GroupCommerceProductItem"; + + // Listing content + marketplace_listing_title: string; + redacted_description: { + text: string; + }; + custom_title?: string; + + // Pricing + formatted_price: { + text: string; + }; + listing_price: { + amount: string; + currency: string; + amount_with_offset: string; + }; + + // Location + location_text: { + text: string; + }; + location: { + latitude: number; + longitude: number; + reverse_geocode_detailed: { + country_alpha_two: string; + postal_code_trimmed: string; + }; + }; + + // Status flags + is_live: boolean; + is_sold: boolean; + is_pending: boolean; + is_hidden: boolean; + is_draft: boolean; + + // Timing + creation_time: number; + + // Seller information + marketplace_listing_seller: { + __typename: "User"; + id: string; + name: string; + profile_picture?: { + uri: string; + }; + join_time?: number; + }; + + // Vehicle-specific fields (for automotive listings) + vehicle_make_display_name?: string; + vehicle_model_display_name?: string; + vehicle_odometer_data?: { + unit: "KILOMETERS" | "MILES"; + value: number; + }; + vehicle_transmission_type?: "AUTOMATIC" | "MANUAL"; + vehicle_exterior_color?: string; + vehicle_interior_color?: string; + vehicle_condition?: "EXCELLENT" | "GOOD" | "FAIR" | "POOR"; + vehicle_fuel_type?: string; + vehicle_trim_display_name?: string; + + // Category and commerce + marketplace_listing_category_id: string; + condition?: string; + + // Commerce features + delivery_types?: string[]; + is_shipping_offered?: boolean; + is_buy_now_enabled?: boolean; + can_buyer_make_checkout_offer?: boolean; + + // Communication + messaging_enabled?: boolean; + first_message_suggested_value?: string; + + // Metadata + logging_id: string; + reportable_ent_id: string; + origin_target?: { + __typename: "Marketplace"; + id: string; + }; + + // Related listings (for part-out sellers) + marketplace_listing_sets?: { + edges: Array<{ + node: { + canonical_listing: { + id: string; + marketplace_listing_title: string; + is_live: boolean; + is_sold: boolean; + formatted_price: { text: string }; + }; + }; + }>; + }; +} +``` + +### Example Data Extracted (Current Structure) +```json +{ + "__typename": "GroupCommerceProductItem", + "marketplace_listing_title": "2012 Mazda MAZDA 3 PART-OUT", + "id": "1211645920845312", + "redacted_description": { + "text": "FOR PARTS ONLY!!!" + }, + "custom_title": "2012 Mazda 3 part-out", + "creation_time": 1760450080, + "location_text": { + "text": "Toronto, ON" + }, + "is_live": true, + "is_sold": false, + "is_pending": false, + "is_hidden": false, + "formatted_price": { + "text": "FREE" + }, + "listing_price": { + "amount_with_offset": "0", + "currency": "CAD", + "amount": "0.00" + }, + "condition": "USED", + "logging_id": "24676483845336407", + "marketplace_listing_category_id": "807311116002614", + "marketplace_listing_seller": { + "__typename": "User", + "id": "61570613529010", + "name": "Jay Heshin", + "profile_picture": { + "uri": "https://scontent-yyz1-1.xx.fbcdn.net/v/t39.30808-1/480952111_122133462296687117_4145652046222010716_n.jpg?stp=cp6_dst-jpg_s50x50_tt6&_nc_cat=108&ccb=1-7&_nc_sid=e99d92&_nc_ohc=x_DTkeriVbgQ7kNvwEqT_x3&_nc_oc=Adnqnqf4YsZxgMIkR2mSFrdLb6-BDw4omCWqG_cqB-H0uXGgK1l4-T-fLSGB_CQJEKo&_nc_zt=24&_nc_ht=scontent-yyz1-1.xx&_nc_gid=7GnSwn4MSbllAgGWJy0RTQ&oh=00_AfpY66l8w-LvHvZ6tTgiD9Qh-Or_Udc-OaFiVL9pQ0YXsg&oe=697797CD" + } + }, + "vehicle_condition": "FAIR", + "vehicle_exterior_color": "white", + "vehicle_interior_color": "", + "vehicle_make_display_name": "Mazda", + "vehicle_model_display_name": "3 part-out", + "vehicle_odometer_data": { + "unit": "KILOMETERS", + "value": 999999 + }, + "vehicle_transmission_type": "AUTOMATIC", + "location": { + "latitude": 43.651428222656, + "longitude": -79.436645507812, + "reverse_geocode_detailed": { + "country_alpha_two": "CA", + "postal_code_trimmed": "M6H 1C1" + } + }, + "delivery_types": ["IN_PERSON"], + "messaging_enabled": true, + "first_message_suggested_value": "Hi, is this available?", + "marketplace_listing_sets": { + "edges": [ + { + "node": { + "canonical_listing": { + "id": "1435935788228627", + "marketplace_listing_title": "2004 Land Rover LR2 PART-OUT", + "is_live": true, + "formatted_price": {"text": "FREE"} + } + } + } + ] + } +} +``` + +## Data Extraction Method + +### Current Method (2026) +Facebook Marketplace listing data is embedded in JSON within `