API de Cenotes
Referencia completa para gestionar información de cenotes, disponibilidad y características.
Descripción General
La API de Cenotes te permite obtener información sobre cenotes en la Península de Yucatán, incluyendo sus ubicaciones, amenidades, precios y disponibilidad en tiempo real. Este es el recurso principal para la plataforma de turismo.
Endpoints
Listar Cenotes
Obtén una lista de cenotes con filtrado y paginación.
GET /api/partner/cenotes
Parámetros
| Parámetro | Tipo | Requerido | Descripción | Ejemplo |
|---|---|---|---|---|
page | integer | No | Número de página (por defecto: 1) | ?page=1 |
perPage | integer | No | Elementos por página (por defecto: 15, máx: 100) | ?perPage=20 |
cursor | string | No | Cursor para paginación basada en cursor | ?cursor=eyJpZCI6ImN0M3QzIn0 |
isActive | boolean | No | Filtrar por estado activo | ?isActive=true |
search | string | No | Buscar por nombre o descripción | ?search=dos ojos |
location.state | string | No | Filtrar por estado | ?location.state=Quintana Roo |
location.municipality | string | No | Filtrar por municipio | ?location.municipality=Tulum |
hasAmenity | string | No | Filtrar por ID de amenidad | ?hasAmenity=snorkeling |
priceRange.min | number | No | Precio mínimo (MXN) | ?priceRange.min=200 |
priceRange.max | number | No | Precio máximo (MXN) | ?priceRange.max=500 |
rating.min | number | No | Calificación mínima (1-5) | ?rating.min=4 |
sortBy | string | No | Campo de ordenamiento | ?sortBy=name |
sortDirection | string | No | Dirección de ordenamiento (asc o desc) | ?sortDirection=asc |
fields | string | No | Campos separados por coma a incluir | ?fields=id,name,location,pricing |
expand | string | No | Recursos relacionados a incluir | ?expand=amenities,reviews |
Campos de Ordenamiento
| Campo | Descripción |
|---|---|
name | Nombre del cenote (alfabético) |
rating | Calificación promedio |
pricing.adult | Precio para adultos |
location.distance | Distancia desde coordenadas (requiere parámetro near) |
createdAt | Fecha de creación |
popularity | Puntuación de popularidad basada en reservas |
Ejemplo de Solicitud
curl -X GET "https://service-gateway.loscenotes.com/api/partner/cenotes?isActive=true&search=dos&sortBy=rating&sortDirection=desc" \
-H "X-API-Key: sk_test_your_api_key" \
-H "Content-Type: application/json"
Ejemplo de Respuesta
{
"success": true,
"message": "cenotes.list_retrieved_successfully",
"data": [
{
"id": "c3n0t3-1234-5678-90ab",
"name": "Cenote Dos Ojos",
"slug": "cenote-dos-ojos",
"description": "Uno de los cenotes más famosos de la Riviera Maya, conocido por sus aguas cristalinas y extenso sistema de cuevas.",
"location": {
"latitude": 20.327423,
"longitude": -87.382118,
"address": "Carretera Tulum-Coba Km 5.5, Quintana Roo, México",
"state": "Quintana Roo",
"municipality": "Tulum",
"zipCode": "77780"
},
"pricing": {
"adult": 350,
"child": 200,
"senior": 250,
"currency": "MXN",
"includes": ["entrada", "chaleco_salvavidas", "equipo_basico_snorkel"]
},
"features": {
"type": "cave",
"depth": {
"min": 1,
"max": 10,
"unit": "meters"
},
"temperature": {
"avg": 24,
"unit": "celsius"
},
"visibility": {
"avg": 100,
"unit": "meters"
},
"difficulty": "beginner",
"accessibility": {
"wheelchairAccessible": false,
"stairsToWater": 15,
"platformAvailable": true
}
},
"amenities": [
{
"id": "parking",
"name": "Estacionamiento",
"category": "facilities",
"available": true,
"cost": 0
},
{
"id": "snorkeling",
"name": "Snorkel",
"category": "activities",
"available": true,
"cost": 0
},
{
"id": "diving",
"name": "Buceo en Cuevas",
"category": "activities",
"available": true,
"cost": 200,
"requirements": ["certification"]
},
{
"id": "restaurant",
"name": "Restaurante",
"category": "dining",
"available": true,
"hours": "08:00-17:00"
}
],
"capacity": {
"daily": 200,
"hourly": 25,
"current": 180
},
"schedule": {
"openTime": "08:00",
"closeTime": "17:00",
"timezone": "America/Cancun",
"daysOpen": [
"monday",
"tuesday",
"wednesday",
"thursday",
"friday",
"saturday",
"sunday"
]
},
"rating": {
"average": 4.7,
"count": 1247,
"breakdown": {
"5": 875,
"4": 280,
"3": 67,
"2": 18,
"1": 7
}
},
"images": [
{
"id": "img_001",
"url": "https://cdn.loscenotes.com/cenotes/dos-ojos/main.jpg",
"alt": "Aguas cristalinas del Cenote Dos Ojos",
"type": "main",
"order": 1
},
{
"id": "img_002",
"url": "https://cdn.loscenotes.com/cenotes/dos-ojos/underwater.jpg",
"alt": "Sistema de cuevas subacuáticas",
"type": "gallery",
"order": 2
}
],
"metadata": {
"featured": true,
"popularity": 95,
"lastUpdated": "2024-01-15T10:30:00Z",
"verifiedAt": "2024-01-10T14:20:00Z"
},
"isActive": true,
"createdAt": "2023-06-15T09:00:00Z",
"updatedAt": "2024-01-15T10:30:00Z"
}
],
"pagination": {
"total": 89,
"perPage": 15,
"currentPage": 1,
"lastPage": 6,
"hasNextPage": true,
"hasPreviousPage": false
},
"currency": {
"base": "MXN",
"rates": {
"USD": 0.058,
"EUR": 0.054,
"CAD": 0.078
},
"lastUpdated": "2024-01-15T08:00:00Z"
}
}
Obtener Detalles del Cenote
Obtén información detallada sobre un cenote específico.
GET /api/partner/cenotes
Parámetros
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
id | string | Sí | ID del cenote (formato UUID) |
expand | string | No | Recursos relacionados a incluir |
fields | string | No | Campos específicos a incluir |
Opciones de Expansión
| Valor | Descripción | Datos Adicionales |
|---|---|---|
amenities | Incluir información detallada de amenidades | Objetos completos de amenidades con descripciones |
reviews | Incluir reseñas recientes | Últimas 10 reseñas con calificaciones |
availability | Incluir disponibilidad actual | Información de capacidad en tiempo real |
nearby | Incluir cenotes cercanos | 5 cenotes más cercanos dentro de 50km |
tours | Incluir tours disponibles | Paquetes de tours que incluyen este cenote |
Ejemplo de Solicitud
curl -X GET "https://service-gateway.loscenotes.com/api/partner/cenotes/c3n0t3-1234-5678-90ab?expand=amenities,reviews" \
-H "X-API-Key: sk_test_your_api_key" \
-H "Content-Type: application/json"
Ejemplo de Respuesta
{
"success": true,
"message": "cenote.retrieved_successfully",
"data": {
"id": "c3n0t3-1234-5678-90ab",
"name": "Cenote Dos Ojos",
"slug": "cenote-dos-ojos",
"description": "Uno de los cenotes más famosos de la Riviera Maya...",
"longDescription": "Cenote Dos Ojos es un sistema de cuevas inundadas ubicado al norte de Tulum...",
"location": {
"latitude": 20.327423,
"longitude": -87.382118,
"address": "Carretera Tulum-Coba Km 5.5, Quintana Roo, México",
"state": "Quintana Roo",
"municipality": "Tulum",
"zipCode": "77780",
"directions": "Desde Tulum, toma la Carretera 109 hacia Cobá. El cenote está a 5.5km a tu derecha.",
"landmarks": [
"Zona Arqueológica de Tulum",
"Gran Cenote",
"Cenote Calavera"
]
},
"contact": {
"phone": "+52 984 123 4567",
"email": "info@cenotedosojos.com",
"website": "https://cenotedosojos.com",
"social": {
"facebook": "@CenoteDosOjos",
"instagram": "@cenotedosojos",
"tripadvisor": "attraction-dos-ojos"
}
},
"pricing": {
"adult": 350,
"child": 200,
"senior": 250,
"currency": "MXN",
"includes": ["entrada", "chaleco_salvavidas", "equipo_basico_snorkel"],
"excludes": ["transporte", "equipo_buceo", "servicio_guia"],
"groupDiscounts": [
{
"minSize": 10,
"discount": 0.1
},
{
"minSize": 20,
"discount": 0.15
}
]
},
"amenities": [
{
"id": "parking",
"name": "Estacionamiento",
"description": "Estacionamiento gratuito disponible para autos y autobuses",
"category": "facilities",
"icon": "parking",
"available": true,
"cost": 0,
"capacity": 50,
"features": ["gratis", "pavimentado", "con_sombra"]
},
{
"id": "restaurant",
"name": "Restaurante",
"description": "Cocina tradicional mexicana y refrescos",
"category": "dining",
"icon": "restaurant",
"available": true,
"hours": "08:00-17:00",
"menu": [
{
"item": "Tacos",
"price": 80,
"description": "Tacos frescos de pescado o pollo"
},
{
"item": "Fruta Fresca",
"price": 50,
"description": "Frutas tropicales de temporada"
}
]
}
],
"reviews": [
{
"id": "rev_001",
"rating": 5,
"title": "¡Absolutamente impresionante!",
"content": "El agua es increíblemente clara y las formaciones de las cuevas son impresionantes...",
"author": "Sarah M.",
"location": "Toronto, Canadá",
"date": "2024-01-10T15:30:00Z",
"verified": true,
"helpful": 15,
"photos": [
{
"url": "https://cdn.loscenotes.com/reviews/rev_001_1.jpg",
"caption": "Agua cristalina"
}
]
}
],
"guidelines": {
"beforeVisit": [
"Llega temprano para evitar multitudes",
"Trae solo protector solar biodegradable",
"Se prefiere pago en efectivo"
],
"duringVisit": [
"No tocar estalactitas o estalagmitas",
"Mantenerse en áreas designadas",
"Respetar la vida silvestre y vegetación"
],
"safety": [
"Los no nadadores deben usar chalecos salvavidas",
"No saltar o bucear sin supervisión",
"Seguir las instrucciones del guía en todo momento"
]
},
"weather": {
"bestVisitingMonths": [
"november",
"december",
"january",
"february",
"march",
"april"
],
"rainySeasonImpact": "minimal",
"temperature": {
"water": {
"avg": 24,
"unit": "celsius"
},
"air": {
"min": 18,
"max": 32,
"unit": "celsius"
}
}
},
"conservation": {
"status": "protected",
"protectedBy": "CONANP",
"conservation_efforts": [
"Monitoreo de calidad del agua",
"Límites de capacidad de visitantes",
"Requisitos de productos biodegradables"
],
"impact": {
"environmental": "low",
"community": "high",
"economic": "high"
}
},
"certifications": [
{
"name": "Bandera Azul",
"issuer": "Fundación para la Educación Ambiental",
"validUntil": "2024-12-31",
"criteria": ["calidad_agua", "gestion_ambiental", "seguridad"]
}
]
}
}
Verificar Disponibilidad
Verifica la disponibilidad en tiempo real para un cenote específico y rango de fechas.
GET /api/partner/cenotes/availability
Parámetros
| Parámetro | Tipo | Requerido | Descripción | Ejemplo |
|---|---|---|---|---|
id | string | Sí | ID del cenote | - |
startDate | string | Sí | Fecha de inicio (ISO 8601) | 2024-07-15 |
endDate | string | No | Fecha de fin (ISO 8601, máx 30 días) | 2024-07-20 |
visitors | integer | No | Número de visitantes | 4 |
time | string | No | Horario específico | 10:00 |
Ejemplo de Solicitud
curl -X GET "https://service-gateway.loscenotes.com/api/partner/cenotes/c3n0t3-1234/availability?startDate=2024-07-15&endDate=2024-07-20&visitors=4" \
-H "X-API-Key: sk_test_your_api_key"
Ejemplo de Respuesta
{
"success": true,
"message": "availability.retrieved_successfully",
"data": {
"cenoteId": "c3n0t3-1234-5678-90ab",
"dateRange": {
"start": "2024-07-15",
"end": "2024-07-20"
},
"requestedVisitors": 4,
"availability": [
{
"date": "2024-07-15",
"available": true,
"capacity": {
"total": 200,
"booked": 45,
"remaining": 155
},
"timeSlots": [
{
"time": "08:00",
"available": true,
"capacity": 25,
"booked": 5,
"remaining": 20
},
{
"time": "10:00",
"available": true,
"capacity": 25,
"booked": 12,
"remaining": 13
},
{
"time": "14:00",
"available": false,
"capacity": 25,
"booked": 25,
"remaining": 0,
"waitlist": true
}
],
"pricing": {
"adult": 350,
"child": 200,
"currency": "MXN"
}
},
{
"date": "2024-07-16",
"available": false,
"reason": "maintenance",
"nextAvailable": "2024-07-17"
}
],
"restrictions": [
{
"type": "weather",
"message": "La lluvia fuerte puede causar cierres temporales",
"datesAffected": ["2024-07-16"]
}
],
"recommendations": [
{
"date": "2024-07-15",
"time": "08:00",
"reason": "Mejor visibilidad y menos multitudes"
}
]
}
}
Cuerpo de la Solicitud
{
"date": "2024-07-15",
"timeSlots": [
{
"time": "08:00",
"capacity": 25,
"available": true
},
{
"time": "10:00",
"capacity": 25,
"available": false,
"reason": "maintenance"
}
],
"specialEvents": [
{
"name": "Taller de Fotografía",
"startTime": "14:00",
"endTime": "16:00",
"capacity": 10
}
]
}
Buscar Cenotes por Ubicación
Busca cenotes cerca de coordenadas específicas.
GET /api/partner/cenotes/search/nearby
Parámetros
| Parámetro | Tipo | Requerido | Descripción | Ejemplo |
|---|---|---|---|---|
latitude | number | Sí | Coordenada de latitud | 20.327423 |
longitude | number | Sí | Coordenada de longitud | -87.382118 |
radius | number | No | Radio de búsqueda en km (por defecto: 50, máx: 200) | 25 |
limit | integer | No | Máx resultados (por defecto: 10, máx: 50) | 15 |
Ejemplo de Solicitud
curl -X GET "https://service-gateway.loscenotes.com/api/partner/cenotes/search/nearby?latitude=20.327423&longitude=-87.382118&radius=25&limit=10" \
-H "X-API-Key: sk_test_your_api_key"
Ejemplo de Respuesta
{
"success": true,
"message": "cenotes.nearby_retrieved_successfully",
"data": [
{
"id": "c3n0t3-1234",
"name": "Cenote Dos Ojos",
"location": {
"latitude": 20.327423,
"longitude": -87.382118
},
"distance": {
"km": 0.0,
"miles": 0.0
},
"rating": 4.7,
"pricing": {
"adult": 350,
"currency": "MXN"
},
"available": true
},
{
"id": "c3n0t3-5678",
"name": "Gran Cenote",
"location": {
"latitude": 20.238942,
"longitude": -87.377892
},
"distance": {
"km": 9.8,
"miles": 6.1
},
"rating": 4.5,
"pricing": {
"adult": 300,
"currency": "MXN"
},
"available": true
}
],
"searchCriteria": {
"center": {
"latitude": 20.327423,
"longitude": -87.382118
},
"radius": 25,
"resultsFound": 2,
"searchTime": "2024-01-15T10:30:00Z"
}
}
Modelos de Datos
Objeto Cenote
interface Cenote {
id: string; // Identificador UUID
name: string; // Nombre para mostrar
slug: string; // Identificador amigable para URL
description: string; // Descripción corta
longDescription?: string; // Descripción detallada
location: Location; // Información geográfica
contact?: Contact; // Información de contacto
pricing: Pricing; // Estructura de precios
features: Features; // Características físicas
amenities: Amenity[]; // Instalaciones disponibles
capacity: Capacity; // Límites de visitantes
schedule: Schedule; // Horarios de operación
rating: Rating; // Calificaciones de reseñas
images: Image[]; // Galería de fotos
guidelines?: Guidelines; // Pautas para visitantes
weather?: WeatherInfo; // Información climática
conservation?: Conservation; // Información ambiental
certifications?: Certification[]; // Certificaciones de calidad
metadata: Metadata; // Metadatos del sistema
isActive: boolean; // Estado activo
createdAt: string; // Marca de tiempo de creación
updatedAt: string; // Marca de tiempo de última actualización
}
Objeto Location
interface Location {
latitude: number; // Grados decimales
longitude: number; // Grados decimales
address: string; // Dirección completa
state: string; // Estado/provincia
municipality: string; // Ciudad/municipio
zipCode?: string; // Código postal
directions?: string; // Direcciones de manejo
landmarks?: string[]; // Puntos de referencia cercanos
}
Objeto Pricing
interface Pricing {
adult: number; // Precio para adultos
child: number; // Precio para niños (típicamente 4-12 años)
senior?: number; // Precio para adultos mayores (65+ años)
currency: string; // Código de moneda ISO
includes: string[]; // Lo que está incluido
excludes?: string[]; // Lo que no está incluido
groupDiscounts?: GroupDiscount[]; // Precios de grupo
}
interface GroupDiscount {
minSize: number; // Tamaño mínimo del grupo
discount: number; // Porcentaje de descuento (0-1)
}
Objeto Features
interface Features {
type: "open" | "semi-open" | "cave" | "underground"; // Tipo de cenote
depth: {
min: number; // Profundidad mínima
max: number; // Profundidad máxima
unit: "meters" | "feet"; // Unidad de profundidad
};
temperature: {
avg: number; // Temperatura promedio
unit: "celsius" | "fahrenheit"; // Unidad de temperatura
};
visibility?: {
avg: number; // Visibilidad promedio
unit: "meters" | "feet"; // Unidad de visibilidad
};
difficulty: "beginner" | "intermediate" | "advanced"; // Nivel de dificultad
accessibility: Accessibility; // Características de accesibilidad
}
interface Accessibility {
wheelchairAccessible: boolean; // Accesible en silla de ruedas
stairsToWater?: number; // Número de escalones
platformAvailable: boolean; // Plataforma para entrada
}
Respuestas de Error
Cenote No Encontrado
{
"success": false,
"error": {
"code": "CENOTE_NOT_FOUND",
"message": "El cenote solicitado no fue encontrado",
"status": 404,
"details": {
"cenoteId": "invalid-id"
}
}
}
Parámetros de Ubicación Inválidos
{
"success": false,
"error": {
"code": "INVALID_COORDINATES",
"message": "Coordenadas de latitud o longitud inválidas",
"status": 400,
"details": {
"latitude": "debe estar entre -90 y 90",
"longitude": "debe estar entre -180 y 180"
}
}
}
Verificación de Disponibilidad Fallida
{
"success": false,
"error": {
"code": "AVAILABILITY_CHECK_FAILED",
"message": "No se pudo verificar la disponibilidad para las fechas especificadas",
"status": 422,
"details": {
"dateRange": "La fecha de fin debe ser posterior a la fecha de inicio",
"maxRange": "El rango de fechas no puede exceder 30 días"
}
}
}
Ejemplos de SDK
SDK de TypeScript
import { LosCenotesClient } from "@loscenotes/partner-sdk";
const client = new LosCenotesClient({
apiKey: "sk_test_your_api_key",
environment: "sandbox",
});
// Listar cenotes con filtros
const cenotes = await client.cenotes.list({
isActive: true,
search: "dos ojos",
sortBy: "rating",
sortDirection: "desc",
expand: ["amenities"],
});
// Obtener cenote específico
const cenote = await client.cenotes.get("c3n0t3-1234", {
expand: ["reviews", "nearby"],
});
// Verificar disponibilidad
const availability = await client.cenotes.checkAvailability("c3n0t3-1234", {
startDate: "2024-07-15",
endDate: "2024-07-20",
visitors: 4,
});
// Buscar por ubicación
const nearby = await client.cenotes.searchNearby({
latitude: 20.327423,
longitude: -87.382118,
radius: 25,
limit: 10,
});
SDK de Python
from loscenotes import LosCenotesClient
client = LosCenotesClient(
api_key='sk_test_your_api_key',
environment='sandbox'
)
# Listar cenotes
cenotes = client.cenotes.list(
is_active=True,
search='dos ojos',
sort_by='rating',
sort_direction='desc'
)
# Obtener cenote específico
cenote = client.cenotes.get(
'c3n0t3-1234',
expand=['reviews', 'nearby']
)
# Verificar disponibilidad
availability = client.cenotes.check_availability(
'c3n0t3-1234',
start_date='2024-07-15',
end_date='2024-07-20',
visitors=4
)
SDK de PHP
<?php
use LosCenotes\LosCenotesClient;
$client = new LosCenotesClient([
'apiKey' => 'sk_test_your_api_key',
'environment' => 'sandbox'
]);
// Listar cenotes
$cenotes = $client->cenotes->getList([
'isActive' => true,
'search' => 'dos ojos',
'sortBy' => 'rating',
'sortDirection' => 'desc'
]);
// Obtener cenote específico
$cenote = $client->cenotes->get('c3n0t3-1234', [
'expand' => ['reviews', 'nearby']
]);
// Verificar disponibilidad
$availability = $client->cenotes->checkAvailability('c3n0t3-1234', [
'startDate' => '2024-07-15',
'endDate' => '2024-07-20',
'visitors' => 4
]);
?>
Próximos Pasos
- API de Reservas - Reservar visitas a cenotes
- API Overview - Referencia general de la API