# POS.DO — Restaurant Discovery Platform (Full Documentation)

> Helping people discover "YOUR next favorite restaurant" through cultural context, real reviews, and time-based offers across 25+ countries.

## What is POS.DO

POS.DO is a multilingual restaurant discovery platform covering 384,000+ restaurants across 25+ countries in 7 languages (Spanish, English, Italian, French, German, Portuguese, Catalan). Unlike rating-centric platforms, POS.DO enriches restaurant profiles with cultural context from Wikidata (nearby monuments, museums, parks) and offers time-based discounts through POS.DO Flow.

## Coverage

- **Countries**: USA (140K), Spain (95K), Italy (43K), Mexico (40K), Colombia (21K), Dominican Republic (3K), Puerto Rico (2K), France, Germany, Portugal, Venezuela, and more
- **Reviews**: 4.28M+ verified reviews with full text, ratings, photos, and owner responses
- **Data per restaurant**: Name, address, coordinates, Google rating, reviews, photos, opening hours, services, cuisine type, price range, cultural context
- **Languages**: es, en, it, fr, de, pt, ca

## Key Features

- **Restaurant Search**: Search by city, cuisine, price range, rating, features (terrace, wifi, delivery, parking, accessible)
- **Detailed Profiles**: Full restaurant info with photos, reviews, hours, services, amenities
- **Cultural Context**: Wikidata-powered nearby landmarks, monuments, museums, heritage sites
- **POS.DO Flow**: Time-based discounts ("Tu hora, tu precio") — off-peak hours have bigger discounts, similar to yield management in hospitality
- **Explore by Landmark**: Find restaurants near specific landmarks (e.g., "restaurants near Sagrada Familia")
- **Web Stories**: AMP stories for restaurants in 7 languages

## URL Structure

- Restaurant profile: `https://pos.do/{lang}/{city}/restaurante/{slug}` (es) or `https://pos.do/{lang}/{city}/restaurant/{slug}` (en/fr/de/it/pt/ca)
- City page: `https://pos.do/{lang}/{city}`
- Web Stories: `https://pos.do/{lang}/web-stories/{slug}`

## API for AI Agents (WebMCP)

POS.DO exposes structured tools for AI agents via WebMCP:

| Tool | Endpoint | Description |
|------|----------|-------------|
| searchRestaurants | GET /api/webmcp/search?city={city} | Search restaurants in a city with filters |
| getRestaurantDetails | GET /api/webmcp/restaurant/{slug} | Full restaurant profile |
| getRestaurantReviews | GET /api/webmcp/restaurant/{slug}/reviews | Paginated reviews with ratings |
| getFlowOffers | GET /api/webmcp/flow/offers/{slug} | Time-based discount offers |
| makeFlowReservation | POST /api/webmcp/flow/reserve | Book at discounted time |
| exploreNearLandmark | GET /api/webmcp/explore/landmark?landmark={name} | Restaurants near a landmark |
| getRestaurantContext | GET /api/webmcp/explore/context/{slug} | Cultural context around a restaurant |

**No authentication required.** Rate limit: 60 req/min, 10,000 req/day.

## WebMCP Manifest

Tool manifest available at: `https://pos.do/.well-known/webmcp.json`

---

## Detailed API Documentation

### 1. searchRestaurants

Search restaurants in a specific city with optional filters for cuisine, price, and features.

**Request:**
```
GET /api/webmcp/search?city=Madrid&cuisine=italian&limit=3
```

**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| city | string | Yes | City name (e.g., "Madrid", "New York", "Barcelona") |
| query | string | No | Free-text search (e.g., "romantic terrace dinner") |
| cuisine | string | No | Cuisine filter: italian, japanese, mexican, spanish, chinese, indian, seafood, vegan, mediterranean, american, asian |
| price_max | integer | No | Maximum price level 1-4 (1=budget, 4=fine dining) |
| features | string | No | Comma-separated: terrace, wifi, parking, delivery, accessible |
| limit | integer | No | Max results 1-20 (default 10) |

**Response:**
```json
{
  "success": true,
  "city": "Madrid",
  "coordinates": { "lat": 40.4168, "lng": -3.7038, "radius": 10, "restaurant_count": 7338 },
  "count": 3,
  "restaurants": [
    {
      "name": "Trattoria Roma",
      "slug": "trattoria-roma-madrid",
      "city": "Madrid",
      "cuisine_type": "Italian",
      "google_rating": "4.5",
      "google_reviews_count": 234,
      "price_range": "€€",
      "price_level": 2,
      "distance_km": 1.2,
      "distance_formatted": "1.2km",
      "address": "Calle Gran Vía 42, Madrid",
      "neighborhood": "Centro",
      "main_photo_url": "https://lh3.googleusercontent.com/...",
      "has_outdoor_seating": true,
      "has_wifi": true,
      "has_delivery": false,
      "has_takeaway": true,
      "has_dine_in": true,
      "is_wheelchair_accessible": false,
      "url": "/es/madrid/restaurante/trattoria-roma-madrid",
      "opening_hours": "{\"Monday\":[\"12:00-23:00\"], ...}",
      "amenities": ["terrace", "wifi", "cards accepted"],
      "meal_types": ["lunch", "dinner"],
      "flow_discount": 20,
      "flow_start": "14:00",
      "flow_until": "15:30",
      "flow_is_active": true,
      "cultural_context": [
        { "name": "Puerta del Sol", "type": "plaza", "distance_m": 350 }
      ]
    }
  ],
  "source": "pos.do"
}
```

### 2. getRestaurantDetails

Get complete profile for a single restaurant including photos, hours, services, Flow offers, and cultural context.

**Request:**
```
GET /api/webmcp/restaurant/cafe-turo
```

**Response:**
```json
{
  "success": true,
  "restaurant": {
    "name": "Café Turó",
    "slug": "cafe-turo",
    "city": "Barcelona",
    "country": "Spain",
    "country_code": "ES",
    "address": "Carrer del Tenor Viñas, 1, Sarrià-Sant Gervasi, 08021 Barcelona",
    "neighborhood": "Sarrià-Sant Gervasi",
    "cuisine_type": "Mediterránea, Tapas",
    "google_rating": "3.9",
    "google_reviews_count": 1342,
    "price_level": null,
    "coordinates": { "lat": "41.3948910", "lng": "2.1419662" },
    "phone": null,
    "main_photo_url": "https://lh3.googleusercontent.com/...",
    "google_photos": [],
    "opening_hours": ["9AM-12AM"],
    "has_delivery": false,
    "has_takeaway": true,
    "has_dine_in": true,
    "has_outdoor_seating": true,
    "has_wifi": true,
    "has_parking": true,
    "is_wheelchair_accessible": false,
    "allows_pets": false,
    "serves_vegetarian": false,
    "serves_vegan": false,
    "google_about": { "Crowd": {}, "Amenities": {} },
    "about_us": "Welcome to our restaurant...",
    "flow_offers_today": [
      {
        "offer_id": 123,
        "discount_percentage": 15,
        "start_time": "14:00",
        "end_time": "15:30",
        "remaining_covers": 8,
        "is_currently_active": true
      }
    ],
    "cultural_context": {
      "nearby_places": [
        {
          "name": "Restaurant Can Punyetes",
          "type": "edificio",
          "distance_m": 237,
          "wikidata_id": "Q126377411",
          "image_url": "https://upload.wikimedia.org/...",
          "heritage_status": "Bien con protección urbanística",
          "is_heritage": true
        }
      ]
    },
    "url": "https://pos.do/es/barcelona/restaurante/cafe-turo"
  },
  "source": "pos.do"
}
```

### 3. getRestaurantReviews

Get paginated customer reviews with rating distribution.

**Request:**
```
GET /api/webmcp/restaurant/cafe-turo/reviews?limit=2&sort=recent
```

**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| slug | path | Yes | Restaurant URL slug |
| rating | integer | No | Filter by exact star rating (1-5) |
| sort | string | No | "recent" (default), "rating_high", "rating_low" |
| limit | integer | No | Max reviews 1-30 (default 10) |
| offset | integer | No | Pagination offset (default 0) |

**Response:**
```json
{
  "success": true,
  "restaurant_name": "Café Turó",
  "total_reviews": 100,
  "rating_distribution": { "1": 13, "2": 4, "3": 7, "4": 16, "5": 60 },
  "average_rating": "3.9",
  "reviews": [
    {
      "author_name": "María G.",
      "rating": 4,
      "review_text": "Bar de toda la vida que me gusta mucho ir",
      "review_date": "2026-01-01",
      "language": "es",
      "review_photos": null,
      "owner_response": null,
      "is_local_guide": false,
      "platform": "google"
    }
  ],
  "source": "pos.do"
}
```

### 4. bookFlowReservation — getOffers

Get today's time-based discount offers for a restaurant.

**Request:**
```
GET /api/webmcp/flow/offers/cafe-turo
```

**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| slug | path | Yes | Restaurant URL slug |
| date | string | No | Date in YYYY-MM-DD (default: today) |

**Response:**
```json
{
  "success": true,
  "restaurant_name": "Café Turó",
  "date": "2026-02-14",
  "day_name": "Friday",
  "timezone": "Europe/Madrid",
  "offers_count": 2,
  "offers": [
    {
      "offer_id": 123,
      "discount_percentage": 20,
      "start_time": "14:00",
      "end_time": "15:30",
      "remaining_covers": 8,
      "is_currently_active": false,
      "is_upcoming": true,
      "is_past": false
    },
    {
      "offer_id": 124,
      "discount_percentage": 15,
      "start_time": "19:00",
      "end_time": "20:00",
      "remaining_covers": 12,
      "is_currently_active": false,
      "is_upcoming": true,
      "is_past": false
    }
  ],
  "source": "pos.do"
}
```

### 4b. bookFlowReservation — makeReservation

Book a table at a Flow-discounted time slot.

**Request:**
```
POST /api/webmcp/flow/reserve
Content-Type: application/json

{
  "slug": "cafe-turo",
  "yield_offer_id": 123,
  "guest_name": "John Smith",
  "guest_email": "john@example.com",
  "guest_phone": "+34600123456",
  "party_size": 2,
  "notes": "Window table please"
}
```

**Response (success):**
```json
{
  "success": true,
  "message": "Reserved at 14:00 with Flow reward -20%",
  "reservation_id": 456,
  "prize_claimed": false,
  "source": "pos.do"
}
```

**Response (error — no seats):**
```json
{
  "success": false,
  "message": "Not enough seats available for this time slot.",
  "source": "pos.do"
}
```

### 5a. exploreNearby — nearLandmark

Find restaurants near a famous landmark.

**Request:**
```
GET /api/webmcp/explore/landmark?landmark=Sagrada+Familia&city=Barcelona&radius=500&limit=3
```

**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| landmark | string | Yes | Landmark name (e.g., "Sagrada Familia", "Colosseum") |
| city | string | No | City hint for disambiguation |
| radius | integer | No | Radius in meters 200-5000 (default 1000) |
| limit | integer | No | Max results 1-15 (default 10) |

**Response:**
```json
{
  "success": true,
  "landmark": {
    "name": "Basilica and Expiatory Church of the Holy Family",
    "description": "basilica under construction since 1882 in Barcelona, Spain",
    "wikidata_id": "Q48435",
    "lat": 41.40369,
    "lng": 2.17433,
    "type": "minor basilica",
    "image_url": "https://upload.wikimedia.org/..."
  },
  "restaurants_count": 3,
  "restaurants": [
    {
      "name": "Restaurant Example",
      "slug": "restaurant-example-barcelona",
      "city": "Barcelona",
      "cuisine_type": "Mediterranean",
      "google_rating": "4.3",
      "google_reviews_count": 180,
      "distance_m": 120,
      "main_photo_url": "https://lh3.googleusercontent.com/...",
      "has_outdoor_seating": true,
      "has_delivery": false
    }
  ],
  "source": "pos.do"
}
```

### 5b. exploreNearby — restaurantContext

Get cultural context around a specific restaurant.

**Request:**
```
GET /api/webmcp/explore/context/cafe-turo
```

**Response:**
```json
{
  "success": true,
  "restaurant_name": "Café Turó",
  "cultural_context": {
    "nearby_places": [
      {
        "name": "Restaurant Can Punyetes",
        "description": "building in Barcelona in Sarrià - Sant Gervasi district",
        "type": "edificio",
        "distance_m": 237,
        "distance_text": "A 237m",
        "wikidata_id": "Q126377411",
        "image_url": "https://upload.wikimedia.org/...",
        "heritage_status": "Bien con protección urbanística",
        "is_heritage": true
      },
      {
        "name": "Escultura La Sardana",
        "description": "Public art in Barcelona",
        "type": "monumento",
        "distance_m": 253,
        "wikidata_id": "Q126680372",
        "image_url": "https://upload.wikimedia.org/...",
        "is_heritage": false
      }
    ],
    "count": 8,
    "has_heritage_sites": true,
    "fetched_at": "2026-02-14T10:30:00Z"
  },
  "source": "pos.do"
}
```

---

## Use Cases for AI Agents

1. **"Find me Italian restaurants in Barcelona with outdoor seating"**
   → `GET /api/webmcp/search?city=Barcelona&cuisine=italian&features=terrace`

2. **"What are the reviews like for Café Turó?"**
   → `GET /api/webmcp/restaurant/cafe-turo/reviews?sort=recent&limit=5`

3. **"Where can I eat near the Colosseum in Rome?"**
   → `GET /api/webmcp/explore/landmark?landmark=Colosseum&city=Rome&radius=500`

4. **"Any lunch deals available right now in Madrid?"**
   → `GET /api/webmcp/search?city=Madrid` then `GET /api/webmcp/flow/offers/{slug}` for each result

5. **"Tell me about the cultural area around this restaurant"**
   → `GET /api/webmcp/explore/context/{slug}`

6. **"Book a table at Café Turó with the 20% discount"**
   → First: `GET /api/webmcp/flow/offers/cafe-turo` to get offer_id
   → Then: `POST /api/webmcp/flow/reserve` with offer_id and guest details

7. **"Show me the best-rated restaurants in New York"**
   → `GET /api/webmcp/search?city=New+York&limit=10` (results sorted by weighted rating)

## Error Handling

All endpoints return consistent error format:
```json
{
  "success": false,
  "error": "City not found",
  "source": "pos.do"
}
```

Common HTTP status codes:
- 200: Success
- 404: Resource not found (city, restaurant, landmark)
- 422: Validation error (invalid parameters, offer expired)
- 429: Rate limit exceeded
- 500: Server error

## Sitemaps

- Main: `https://pos.do/sitemap.xml`
- Restaurants: `https://pos.do/sitemaps/sitemap_restaurants_{n}.xml`
- Web Stories: `https://pos.do/sitemaps/web-stories-index.xml`

## Contact

- Website: https://pos.do
- Email: info@pos.do