Endpoints - Villes

Les endpoints de villes permettent d'accéder aux informations sur les villes et leurs configurations.

Pagination

GET /public/cities, GET /public/city-groups et les sous-ressources /public/cities/:id/… renvoient { data, meta }. Query page (défaut 1), pageSize (défaut 20, max 100). SDK : client.public.cities.*.

Liste des villes

Récupère la liste de toutes les villes actives avec leurs données complètes.

Requête

GET /public/cities

Réponse

[
  {
    "id": "city-uuid",
    "name": "Paris",
    "country": "France",
    "population": 2161000,
    "status": "ACTIF",
    "outOfTheBins": "Les déchets volumineux doivent être déposés en déchetterie...",
    "presentationOfBins": "Présentez vos bacs la veille au soir...",
    "returnOfBins": "Rentrez vos bacs après la collecte...",
    "respectOfCalendar": "Il est important de respecter le calendrier...",
    "holidays": "Les jours fériés peuvent modifier les jours de collecte...",
    "cityGroup": {
      "id": "group-uuid",
      "name": "Paris Métropole",
      "type": "METROPOLE"
    },
    "wasteTypes": [
      {
        "id": "waste-type-uuid",
        "name": "Verre",
        "description": "Bouteilles et bocaux en verre",
        "instructions": "Vider et rincer avant de jeter",
        "color": "#2E7D32",
        "colorLight": "#4CAF50",
        "icon": "glass",
        "imageUrl": "https://...",
        "details": [
          {
            "id": "detail-uuid",
            "material": "Bouteille en verre",
            "description": "Bouteille en verre transparent ou coloré",
            "instructions": "Retirer les bouchons et capsules",
            "imageUrl": "https://..."
          }
        ]
      }
    ],
    "wasteCollectionPlaces": [
      {
        "id": "place-uuid",
        "name": "Centre-ville",
        "collectionDays": [
          {
            "id": "day-uuid",
            "name": "Lundi",
            "wasteTypeId": "waste-type-uuid",
            "description": "Collecte du verre",
            "biweekly": false,
            "startDate": "2024-01-01T00:00:00.000Z"
          }
        ],
        "exceptions": [
          {
            "id": "exception-uuid",
            "dateFrom": "2024-12-25T00:00:00.000Z",
            "dateTo": "2024-12-25T23:59:59.999Z",
            "wasteTypeId": "waste-type-uuid",
            "name": "Noël",
            "description": "Pas de collecte le jour de Noël"
          }
        ],
        "attachedLocations": [
          {
            "id": "location-uuid",
            "name": "Rue de la Paix",
            "reference": "REF001",
            "latitude": 48.8566,
            "longitude": 2.3522
          }
        ]
      }
    ],
    "challenges": [
      {
        "id": "challenge-uuid",
        "name": "Apprenti Trieur",
        "description": "Apprenez les bases du tri",
        "enabled": true,
        "startDate": "2024-01-01T00:00:00.000Z",
        "endDate": null,
        "order": 1,
        "series": [
          {
            "id": "serie-uuid",
            "name": "Série 1",
            "description": "Première série de questions",
            "order": 1,
            "quizQuestions": [
              {
                "id": "question-uuid",
                "material": "Bouteille en plastique",
                "question": "Dans quel bac dois-je jeter cette bouteille ?",
                "correctWasteTypeId": "waste-type-uuid",
                "order": 1
              }
            ]
          }
        ],
        "badge": {
          "id": "badge-uuid",
          "name": "Apprenti Trieur",
          "description": "Vous avez complété votre premier challenge",
          "icon": "star",
          "imageUrl": "https://..."
        }
      }
    ],
    "recyclingPoints": [
      {
        "id": "point-uuid",
        "name": "Déchetterie Centre",
        "address": "123 Rue Example",
        "latitude": 48.8566,
        "longitude": 2.3522,
        "openingHours": "Lun-Ven: 9h-18h"
      }
    ],
    "quizQuestions": [
      {
        "id": "quiz-uuid",
        "material": "Bouteille en plastique",
        "question": "Dans quel bac dois-je jeter cette bouteille ?",
        "correctWasteTypeId": "waste-type-uuid",
        "order": 1
      }
    ]
  }
]

Exemple d'utilisation

const response = await fetch('https://api.wast-o.com/public/cities');
const cities = await response.json();

// Trouver une ville par nom
const paris = cities.find(city => city.name === 'Paris');
console.log(paris.wasteTypes);

Détails d'une ville

Récupère les détails complets d'une ville spécifique par son ID.

Requête

GET /public/cities/:id

Paramètres

id (string, requis) : Identifiant unique de la ville (UUID)

Réponse

La réponse est identique à un élément de la liste des villes (voir ci-dessus).

Exemple d'utilisation

const cityId = 'city-uuid';
const response = await fetch(`https://api.wast-o.com/public/cities/${cityId}`);
const city = await response.json();

console.log(`Ville: ${city.name}`);
console.log(`Types de déchets: ${city.wasteTypes.length}`);
console.log(`Lieux de collecte: ${city.wasteCollectionPlaces.length}`);

Codes d'erreur

404 Not Found : La ville avec l'ID spécifié n'existe pas ou n'est pas active

Groupes de villes

Récupère la liste de tous les groupes de villes (communautés de communes, métropoles, etc.).

Requête

GET /public/city-groups

Réponse

[
  {
    "id": "group-uuid",
    "name": "Paris Métropole",
    "type": "METROPOLE",
    "code": "PM",
    "siren": "123456789",
    "cities": [
      {
        "id": "city-uuid",
        "name": "Paris",
        "country": "France",
        "population": 2161000
      }
    ],
    "_count": {
      "cities": 1
    }
  }
]

Exemple d'utilisation

const response = await fetch('https://api.wast-o.com/public/city-groups');
const cityGroups = await response.json();

// Trouver toutes les villes d'un groupe
const metropole = cityGroups.find(group => group.name === 'Paris Métropole');
console.log(`Villes dans la métropole: ${metropole.cities.length}`);

Schémas de données

City

interface City {
  id: string;
  name: string;
  country: string;
  population?: number;
  status: 'ACTIF' | 'NON_ACTIF';
  outOfTheBins?: string;
  presentationOfBins?: string;
  returnOfBins?: string;
  respectOfCalendar?: string;
  holidays?: string;
  cityGroup?: {
    id: string;
    name: string;
    type: string;
  };
  wasteTypes: WasteType[];
  wasteCollectionPlaces: WasteCollectionPlace[];
  challenges: Challenge[];
  recyclingPoints: RecyclingPoint[];
  quizQuestions: QuizQuestion[];
}

WasteType

interface WasteType {
  id: string;
  name: string;
  description?: string;
  instructions?: string;
  color?: string;
  colorLight?: string;
  icon?: string;
  imageUrl?: string;
  details?: WasteTypeDetail[];
}

interface WasteTypeDetail {
  id: string;
  material: string;
  description?: string;
  instructions?: string;
  imageUrl?: string;
}

WasteCollectionPlace

interface WasteCollectionPlace {
  id: string;
  name: string;
  collectionDays: WasteCollectionDay[];
  exceptions: WasteCollectionException[];
  attachedLocations?: AttachedLocation[];
}

interface WasteCollectionDay {
  id: string;
  name: string; // "Lundi", "Mardi", etc.
  wasteTypeId: string;
  description?: string;
  biweekly?: boolean;
  startDate?: string;
}

interface WasteCollectionException {
  id: string;
  dateFrom: string;
  dateTo?: string;
  wasteTypeId: string;
  name?: string;
  description?: string;
}

## Sous-ressources d’une ville

Toutes paginées (`page`, `pageSize`) :

| Méthode | Path | SDK |
|---|---|---|
| GET | `/public/cities/:id/recycling-points` | `getRecyclingPoints` |
| GET | `/public/cities/:id/waste-types` | `getWasteTypes` |
| GET | `/public/cities/:id/waste-collection-places` | `getWasteCollectionPlaces` |
| GET | `/public/cities/:id/challenges` | `getChallenges` |
| GET | `/public/cities/:id/badges` | `getBadges` |
| GET | `/public/cities/:id/operational-zones` | `getOperationalZones` |

Zones opérationnelles : uniquement `status: ACTIVE` et en vigueur. Types : `TRAVAUX` | `PARKING_PROVISOIRE` | `ZONE_INTERDITE` | `AUTRE`.

## Localiser un lieu par GPS

Pas de méthode SDK dédiée.

```http
GET /public/waste-collection-places/locate?lat=48.85&lon=2.35

lat (−90…90) et lon (−180…180) requis. Jusqu’à 5 lieux les plus proches (ordre = proximité), chacun avec sa city.

Groupes de villes (détail)

GET /public/city-groups/:id
GET /public/city-groups/:id/cities?page=1&pageSize=20

Pas de client.public.cityGroups. Types de groupe : AGGLOMERATION | COMMUNAUTE | METROPOLE | SYNDICAT | AUTRE.

Horaires d'ouverture (`RecyclingPoint`)

Deux modes de saisie via details.hoursMode :

Mode	Champ	Description
`text`	`hours` (string)	Texte libre, ex. `Lun–Sam 8h–18h`
`structured`	`details.openingHours` (JSON)	Créneaux hebdomadaires stockés en UTC+0

Schéma `details.openingHours`

{
  "version": 1,
  "storage": "utc",
  "rules": [
    {
      "days": ["monday", "tuesday", "wednesday", "thursday", "friday"],
      "slots": [
        { "open": "04:00", "close": "08:00" },
        { "open": "10:00", "close": "14:00" }
      ]
    }
  ],
  "exceptions": [
    { "date": "2026-12-25", "closed": true, "label": "Noël" }
  ]
}

days : monday … sunday
slots : heures HH:mm en UTC
hours (top-level) : résumé texte généré côté client pour rétrocompat (cartes, apps legacy)
Conversion fuseau : côté client via @wasto/sdk (convertLocalToUtc / convertUtcToLocal, fuseau navigateur)

Helpers SDK : validateOpeningHours, formatOpeningHoursSummary, formatOpeningHoursWeekly, resolveHoursDisplay, isOpenNow.

Liste des villes​

Requête​

Réponse​

Exemple d'utilisation​

Détails d'une ville​

Requête​

Paramètres​

Réponse​

Exemple d'utilisation​

Codes d'erreur​

Groupes de villes​

Requête​

Réponse​

Exemple d'utilisation​

Schémas de données​

City​

WasteType​

WasteCollectionPlace​

Groupes de villes (détail)​

Horaires d'ouverture (RecyclingPoint)​

Schéma details.openingHours​

Liste des villes

Requête

Réponse

Exemple d'utilisation

Détails d'une ville

Requête

Paramètres

Réponse

Exemple d'utilisation

Codes d'erreur

Groupes de villes

Requête

Réponse

Exemple d'utilisation

Schémas de données

City

WasteType

WasteCollectionPlace

Groupes de villes (détail)

Horaires d'ouverture (`RecyclingPoint`)

Schéma `details.openingHours`