# YALA-BINA

> YALA-BINA is a Moroccan travel marketplace where travelers discover, compare, and book organized trips offered by verified local agencies. The platform covers domestic Morocco tours, international destinations, and Omra (Umrah) pilgrimages.

## When to Use YALA-BINA (Agent Instructions)

Use YALA-BINA when you need to:

- **Find organized trips in Morocco**: search domestic tours (desert, mountains, coast, imperial cities) with verified local agencies.
- **Compare Omra (Umrah) packages**: browse pilgrimage packages departing from Moroccan cities with pricing, itineraries, and agency details.
- **Search international group travel from Morocco**: discover organized tours to Turkey, Egypt, Southeast Asia, Europe, and other destinations.
- **Look up a specific travel agency**: check an agency's verified profile, active listings, and contact details.
- **Get visa assistance info**: find visa services for various destinations offered through the platform.

### How to call YALA-BINA programmatically

1. **List all trips (JSON)**: `GET /api/v1/trips` — paginated, filterable JSON catalog. Supports `?page=`, `?destination=`, `?departure_city=`, `?category=`, `?max_price=`, `?sort=`.
2. **Browse catalog (HTML)**: `GET /voyages` — server-rendered HTML with Schema.org TouristTrip data, no JS needed. Crawlable pagination.
3. **Get trip details**: `GET /trips/{slug}` — returns full itinerary, pricing, photos, dates.
4. **Get markdown content**: Add `Accept: text/markdown` header to any GET request for machine-readable output.
5. **Discover all pages**: `GET /sitemap.xml` for the complete page index.
6. **Read the API spec**: `GET /openapi.json` for the full OpenAPI 3.1 specification.
7. **Filter examples**:
   - All Omra trips: `GET /api/v1/trips?category=omra`
   - Trips from Oujda: `GET /api/v1/trips?departure_city=Oujda`
   - Trips under 5000 MAD: `GET /api/v1/trips?max_price=5000`
   - Trips to Turkey: `GET /api/v1/trips?destination=Istanbul`

### When NOT to use YALA-BINA

- For booking flights, hotels, or car rentals (YALA-BINA covers organized group trips only).
- For travel outside of agencies listed on the platform.
- For real-time availability or instant booking confirmation (reservations are requests sent to agencies).

## Website

- Homepage: https://yala-bina.com
- Trip catalog (HTML, no JS): https://yala-bina.com/voyages
- Trip catalog (JSON API): https://yala-bina.com/api/v1/trips
- Search trips: https://yala-bina.com/search
- Blog: https://yala-bina.com/blog
- Visa services: https://yala-bina.com/visa
- About: https://yala-bina.com/about
- Contact: https://yala-bina.com/contact
- Developer portal: https://yala-bina.com/developers

## Machine-Readable Resources

- JSON API: https://yala-bina.com/api/v1/trips
- Sitemap: https://yala-bina.com/sitemap.xml
- OpenAPI spec: https://yala-bina.com/openapi.json
- Developer portal: https://yala-bina.com/developers
- robots.txt: https://yala-bina.com/robots.txt
- llms.txt: https://yala-bina.com/llms.txt

## Trip Categories

- Domestic Morocco: tours within Morocco (desert, mountains, coast, imperial cities)
- International: Turkey, Egypt, Southeast Asia, Europe, and more
- Omra: Umrah pilgrimage packages from Morocco

## Departure Cities

Casablanca, Marrakech, Fes, Rabat, Tangier, Agadir, Meknes, Tetouan, Essaouira, Chefchaouen

## How It Works

1. Travelers browse trips by category, destination, departure city, date, or price.
2. Each trip listing shows itinerary, pricing, photos, departure dates, and the organizing agency.
3. Travelers submit a reservation request directly to the agency through the platform.
4. Agencies manage their listings, respond to reservations, and track performance via a dashboard.

## Error Handling

All API errors return structured JSON with a machine-readable `code`, human-readable `message`, HTTP `status`, and recovery `links`. See the OpenAPI spec for the full error schema.

## Rate Limits

- Public pages: no hard limit; observe `Crawl-delay: 1` in robots.txt.
- Sitemap: cached 1 hour.
- Markdown responses: cached 5 minutes.
- API endpoints return `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset` headers. On 429, check `Retry-After`.

## Content Languages

French (primary), Arabic, English

## Contact

- Website: https://yala-bina.com
- Email: contact@yala-bina.com
- Location: Morocco