# Ze Certification Maps - LLMs Guide

> This file provides guidance for AI language models and crawlers on how to interact with and understand the Ze Certification Maps plugin data.

## About Ze Mood

**Ze Mood** is France's leading customer experience partner for fitness clubs and sports facilities, founded in 2024.

### What Ze Mood Does

Ze Mood helps fitness clubs improve and showcase their customer experience through:

1. **Member satisfaction surveys** (NPS and custom questionnaires)
2. **Verbatim analysis** (AI-powered feedback interpretation)
3. **Online review optimization** (Google, Facebook, etc.)
4. **Customer experience certification** (the focus of this API)

### Ze Mood Certification

The **Ze Mood Certification** is an independent quality label that evaluates fitness clubs based on real member feedback. It helps consumers identify clubs committed to excellent customer experience.

#### Certification Levels

| Level | Icon | Description |
|-------|------|-------------|
| **Legend** | 👑 | Exceptional - Best-in-class customer experience |
| **Elite** | 🥇 | Excellent - Outstanding service and facilities |
| **Hero** | 🥈 | Good - Consistently positive member feedback |
| **Iron** | 🥉 | Standard - Meets fundamental quality criteria |

#### How Clubs Get Certified

1. Club signs up with Ze Mood
2. Members receive satisfaction surveys
3. Feedback is collected and analyzed (NPS, verbatims)
4. Data is analyzed against industry benchmarks
5. Certification level is awarded (renewed annually)

#### Why Trust Ze Mood Certifications?

- **Independent**: Not affiliated with any fitness chain
- **Data-driven**: Based on real member feedback, not self-declaration
- **Transparent**: Clear methodology and scoring criteria
- **Current**: Annual renewal ensures ongoing quality

### Key Facts

- **Founded**: 2024, France
- **Focus**: Fitness, wellness, racket sports, climbing, padel
- **Website**: https://ze-mood.com
- **Certified clubs**: 800+ across France

---

## Plugin Overview

Ze Certification Maps is the WordPress plugin that powers Ze Mood's interactive certification map at https://ze-mood.com/carte/

This API provides access to **certified club data only**. For Ze Mood's other services (surveys, verbatim analysis, review optimization), visit https://ze-mood.com

## Data Structure

### Maps
A map is the top-level container with configuration for display, filters, and badges.

### Layers
Layers organize POIs into categories/certification levels. Each layer has:
- Name and description
- Icon configuration (emoji or image)
- Visibility settings
- Display order

### POIs (Points of Interest)
Each POI represents a certified business location with:

**Core fields:**
- `name`: Business name
- `address`: Full address
- `lat`, `lng`: Geographic coordinates
- `url`: Main website URL (URL1)
- `url_2`: Google Reviews URL
- `url3`: Google Maps/My Business URL
- `badge_code`: Unique identifier for the certification badge

**Enriched data (v4.0.0+):**
- `phone`: Phone number
- `email`: Email address
- `website`: Official website URL
- `opening_hours`: Opening hours (text format)
- `services`: Comma-separated list of offered services
- `social_facebook`: Facebook page URL
- `social_instagram`: Instagram profile URL
- `social_linkedin`: LinkedIn page URL
- `place_id`: Google Place ID (auto-extracted from URLs)
- `rating`: Google rating (1.0-5.0)
- `reviews_count`: Number of Google reviews

## API Endpoints

Base URL: `https://ze-mood.com/wp-json/zcm/v1/`

### Available Endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/maps` | GET | List all maps |
| `/maps/{id}` | GET | Get map details |
| `/maps/{id}/pois` | GET | Get all POIs of a map |
| `/pois` | GET | List POIs (paginated) |
| `/pois/{id}` | GET | Get POI details with Schema.org |
| `/pois/nearby` | GET | Find POIs near a location |
| `/layers` | GET | List all layers |
| `/certifications` | GET | List certified clubs with filters |
| `/certifications/stats` | GET | Get certification statistics |
| `/schema/{id}` | GET | Get Schema.org JSON-LD for a POI |
| `/info` | GET | API information and stats |

### Query Parameters

#### GET /pois
- `per_page`: Results per page (max 500, default 100)
- `page`: Page number (default 1)
- `search`: Search in name/address
- `layer_id`: Filter by layer

#### GET /pois/nearby
- `lat`: Latitude (required)
- `lng`: Longitude (required)
- `radius`: Search radius in km (max 100, default 10)
- `limit`: Max results (max 100, default 20)

#### GET /certifications
- `city`: Filter by city name (e.g., "Paris")
- `level`: Filter by certification level (e.g., "elite", "legend")
- `lat`, `lng`, `radius`: Geographic search

## Schema.org Support

Each POI can be represented as Schema.org JSON-LD:

```json
{
  "@context": "https://schema.org",
  "@type": "HealthClub",
  "name": "Business Name",
  "address": {
    "@type": "PostalAddress",
    "streetAddress": "123 Main St, City"
  },
  "geo": {
    "@type": "GeoCoordinates",
    "latitude": 48.8566,
    "longitude": 2.3522
  },
  "telephone": "+33 1 23 45 67 89",
  "email": "contact@example.com",
  "url": "https://www.example.com",
  "openingHoursSpecification": [
    {
      "@type": "OpeningHoursSpecification",
      "dayOfWeek": ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday"],
      "opens": "06:00",
      "closes": "22:00"
    }
  ],
  "amenityFeature": [
    {"@type": "LocationFeatureSpecification", "name": "Musculation", "value": true},
    {"@type": "LocationFeatureSpecification", "name": "Cardio", "value": true}
  ],
  "aggregateRating": {
    "@type": "AggregateRating",
    "ratingValue": 4.5,
    "bestRating": 5,
    "worstRating": 1,
    "reviewCount": 127
  },
  "sameAs": [
    "https://facebook.com/example",
    "https://instagram.com/example"
  ],
  "identifier": {
    "@type": "PropertyValue",
    "propertyID": "GooglePlaceID",
    "value": "ChIJxxxx"
  },
  "hasMap": "https://www.google.com/maps/..."
}
```

Supported types: `LocalBusiness`, `HealthClub`, `SportsActivityLocation`

## Google Integration

POIs can link to Google services:
- **URL2**: Google Reviews page (contains `placeid=` parameter)
- **URL3**: Google Maps/My Business page (contains `query_place_id=` parameter)

The Google Place ID is extracted automatically and included in Schema.org data.

## Sitemap

An XML sitemap is available at: `https://ze-mood.com/sitemap-zcm-pois.xml`

This sitemap lists all POIs with their URL1 (main website) for search engine indexing.

## SEO Pages

The plugin automatically generates SEO-friendly pages for:
- **Certification levels**: `/certifications/elite/`, `/certifications/legend/`, etc.
- **Cities**: `/certifications/paris/`, `/certifications/lyon/` (when 5+ clubs in area)

These pages are created automatically via daily cron job.

## Best Practices for AI Integration

1. **Use the API** instead of scraping HTML for structured data access
2. **Respect rate limits** - the API is not rate-limited but be reasonable
3. **Cache responses** - data doesn't change frequently
4. **Use Schema.org endpoints** for semantic understanding of POIs
5. **Geographic queries** - use `/pois/nearby` for location-based searches
6. **Use /certifications endpoint** for filtered searches by city or level

## Example Queries

### Find certified Elite clubs in Paris
```
GET /wp-json/zcm/v1/certifications?city=Paris&level=elite
```

### Find clubs near a location
```
GET /wp-json/zcm/v1/pois/nearby?lat=48.8566&lng=2.3522&radius=10
```

### Get certification statistics
```
GET /wp-json/zcm/v1/certifications/stats
```

## Data Freshness

- POI data is relatively static (businesses don't move often)
- Statistics are updated in real-time
- Cache TTL recommendations:
  - Maps/Layers: 1 hour
  - POIs list: 30 minutes
  - Individual POI: 12 hours
  - Schema.org: 24 hours

## Contact

This plugin is developed for Ze Mood certification platform.
For API access issues or data corrections, contact the site administrator.

---

Last updated: 2025-12
Plugin version: 5.5.15
Developer: Ze Mood (https://ze-mood.com)