Cenotes API

Complete reference for managing cenote information, availability, and features.

Overview

The Cenotes API allows you to retrieve information about cenotes in the Yucatan Peninsula, including their locations, amenities, pricing, and real-time availability. This is the core resource for the tourism platform.

Endpoints

List Cenotes

Retrieve a list of cenotes with filtering and pagination.

GET /partner/cenotes

Parameters

Parameter	Type	Required	Description	Example
`page`	integer	No	Page number (default: 1)	`?page=1`
`perPage`	integer	No	Items per page (default: 15, max: 100)	`?perPage=20`
`cursor`	string	No	Cursor for cursor-based pagination	`?cursor=eyJpZCI6ImN0M3QzIn0`
`isActive`	boolean	No	Filter by active status	`?isActive=true`
`search`	string	No	Search by name or description	`?search=dos ojos`
`location.state`	string	No	Filter by state	`?location.state=Quintana Roo`
`location.municipality`	string	No	Filter by municipality	`?location.municipality=Tulum`
`hasAmenity`	string	No	Filter by amenity ID	`?hasAmenity=snorkeling`
`priceRange.min`	number	No	Minimum price (MXN)	`?priceRange.min=200`
`priceRange.max`	number	No	Maximum price (MXN)	`?priceRange.max=500`
`rating.min`	number	No	Minimum rating (1-5)	`?rating.min=4`
`sortBy`	string	No	Sort field	`?sortBy=name`
`sortDirection`	string	No	Sort direction (`asc` or `desc`)	`?sortDirection=asc`
`fields`	string	No	Comma-separated fields to include	`?fields=id,name,location,pricing`
`expand`	string	No	Related resources to include	`?expand=amenities,reviews`

Sort Fields

Field	Description
`name`	Cenote name (alphabetical)
`rating`	Average rating
`pricing.adult`	Adult price
`location.distance`	Distance from coordinates (requires `near` parameter)
`createdAt`	Creation date
`popularity`	Popularity score based on bookings

Example Request

curl -X GET "https://service-gateway.loscenotes.com/partner/cenotes?isActive=true&search=dos&sortBy=rating&sortDirection=desc" \
  -H "X-API-Key: pk_live_your_api_key" \
  -H "Content-Type: application/json"

Example Response

{
  "success": true,
  "message": "cenotes.list_retrieved_successfully",
  "data": [
    {
      "id": "c3n0t3-1234-5678-90ab",
      "name": "Cenote Dos Ojos",
      "slug": "cenote-dos-ojos",
      "description": "One of the most famous cenotes in the Riviera Maya, known for its crystal-clear waters and extensive cave system.",
      "location": {
        "latitude": 20.327423,
        "longitude": -87.382118,
        "address": "Carretera Tulum-Coba Km 5.5, Quintana Roo, Mexico",
        "state": "Quintana Roo",
        "municipality": "Tulum",
        "zipCode": "77780"
      },
      "pricing": {
        "adult": 350,
        "child": 200,
        "senior": 250,
        "currency": "MXN",
        "includes": ["entrance_fee", "life_jacket", "basic_snorkel_equipment"]
      },
      "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": "Parking",
          "category": "facilities",
          "available": true,
          "cost": 0
        },
        {
          "id": "snorkeling",
          "name": "Snorkeling",
          "category": "activities",
          "available": true,
          "cost": 0
        },
        {
          "id": "diving",
          "name": "Cave Diving",
          "category": "activities",
          "available": true,
          "cost": 200,
          "requirements": ["certification"]
        },
        {
          "id": "restaurant",
          "name": "Restaurant",
          "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": "Crystal clear waters of Cenote Dos Ojos",
          "type": "main",
          "order": 1
        },
        {
          "id": "img_002",
          "url": "https://cdn.loscenotes.com/cenotes/dos-ojos/underwater.jpg",
          "alt": "Underwater cave system",
          "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"
  }
}

Get Cenote Details

Retrieve detailed information about a specific cenote.

GET /partner/cenotes

Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Cenote ID (UUID format)
`expand`	string	No	Related resources to include
`fields`	string	No	Specific fields to include

Expansion Options

Value	Description	Additional Data
`amenities`	Include detailed amenity information	Full amenity objects with descriptions
`reviews`	Include recent reviews	Latest 10 reviews with ratings
`availability`	Include current availability	Real-time capacity information
`nearby`	Include nearby cenotes	5 nearest cenotes within 50km
`tours`	Include available tours	Tour packages that include this cenote

Example Request

curl -X GET "https://service-gateway.loscenotes.com/partner/cenotes/c3n0t3-1234-5678-90ab?expand=amenities,reviews" \
  -H "X-API-Key: pk_live_your_api_key" \
  -H "Content-Type: application/json"

Example Response

{
  "success": true,
  "message": "cenote.retrieved_successfully",
  "data": {
    "id": "c3n0t3-1234-5678-90ab",
    "name": "Cenote Dos Ojos",
    "slug": "cenote-dos-ojos",
    "description": "One of the most famous cenotes in the Riviera Maya...",
    "longDescription": "Cenote Dos Ojos is a flooded cave system located north of Tulum...",
    "location": {
      "latitude": 20.327423,
      "longitude": -87.382118,
      "address": "Carretera Tulum-Coba Km 5.5, Quintana Roo, Mexico",
      "state": "Quintana Roo",
      "municipality": "Tulum",
      "zipCode": "77780",
      "directions": "From Tulum, take Highway 109 towards Coba. The cenote is 5.5km on your right.",
      "landmarks": [
        "Tulum Archaeological Zone",
        "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": ["entrance_fee", "life_jacket", "basic_snorkel_equipment"],
      "excludes": ["transportation", "diving_equipment", "guide_service"],
      "groupDiscounts": [
        {
          "minSize": 10,
          "discount": 0.1
        },
        {
          "minSize": 20,
          "discount": 0.15
        }
      ]
    },
    "amenities": [
      {
        "id": "parking",
        "name": "Parking",
        "description": "Free parking available for cars and buses",
        "category": "facilities",
        "icon": "parking",
        "available": true,
        "cost": 0,
        "capacity": 50,
        "features": ["free", "paved", "shaded"]
      },
      {
        "id": "restaurant",
        "name": "Restaurant",
        "description": "Traditional Mexican cuisine and refreshments",
        "category": "dining",
        "icon": "restaurant",
        "available": true,
        "hours": "08:00-17:00",
        "menu": [
          {
            "item": "Tacos",
            "price": 80,
            "description": "Fresh fish or chicken tacos"
          },
          {
            "item": "Fresh Fruit",
            "price": 50,
            "description": "Seasonal tropical fruits"
          }
        ]
      }
    ],
    "reviews": [
      {
        "id": "rev_001",
        "rating": 5,
        "title": "Absolutely stunning!",
        "content": "The water is incredibly clear and the cave formations are breathtaking...",
        "author": "Sarah M.",
        "location": "Toronto, Canada",
        "date": "2024-01-10T15:30:00Z",
        "verified": true,
        "helpful": 15,
        "photos": [
          {
            "url": "https://cdn.loscenotes.com/reviews/rev_001_1.jpg",
            "caption": "Crystal clear water"
          }
        ]
      }
    ],
    "guidelines": {
      "beforeVisit": [
        "Arrive early to avoid crowds",
        "Bring biodegradable sunscreen only",
        "Cash payment preferred"
      ],
      "duringVisit": [
        "No touching of stalactites or stalagmites",
        "Stay within designated areas",
        "Respect wildlife and vegetation"
      ],
      "safety": [
        "Non-swimmers must wear life jackets",
        "No jumping or diving without supervision",
        "Follow guide instructions at all times"
      ]
    },
    "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": [
        "Water quality monitoring",
        "Visitor capacity limits",
        "Biodegradable product requirements"
      ],
      "impact": {
        "environmental": "low",
        "community": "high",
        "economic": "high"
      }
    },
    "certifications": [
      {
        "name": "Blue Flag",
        "issuer": "Foundation for Environmental Education",
        "validUntil": "2024-12-31",
        "criteria": ["water_quality", "environmental_management", "safety"]
      }
    ]
  }
}

Check Availability

Check real-time availability for a specific cenote and date range.

GET /partner/cenotes/availability

Parameters

Parameter	Type	Required	Description	Example
`id`	string	Yes	Cenote ID	-
`startDate`	string	Yes	Start date (ISO 8601)	`2024-07-15`
`endDate`	string	No	End date (ISO 8601, max 30 days)	`2024-07-20`
`visitors`	integer	No	Number of visitors	`4`
`time`	string	No	Specific time slot	`10:00`

Example Request

curl -X GET "https://service-gateway.loscenotes.com/partner/cenotes/c3n0t3-1234/availability?startDate=2024-07-15&endDate=2024-07-20&visitors=4" \
  -H "X-API-Key: pk_live_your_api_key"

Example Response

{
  "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": "Heavy rain may cause temporary closures",
        "datesAffected": ["2024-07-16"]
      }
    ],
    "recommendations": [
      {
        "date": "2024-07-15",
        "time": "08:00",
        "reason": "Best visibility and fewer crowds"
      }
    ]
  }
}

Request Body

{
  "date": "2024-07-15",
  "timeSlots": [
    {
      "time": "08:00",
      "capacity": 25,
      "available": true
    },
    {
      "time": "10:00",
      "capacity": 25,
      "available": false,
      "reason": "maintenance"
    }
  ],
  "specialEvents": [
    {
      "name": "Photography Workshop",
      "startTime": "14:00",
      "endTime": "16:00",
      "capacity": 10
    }
  ]
}

Search Cenotes by Location

Search for cenotes near specific coordinates.

GET /partner/cenotes/search/nearby

Parameters

Parameter	Type	Required	Description	Example
`latitude`	number	Yes	Latitude coordinate	`20.327423`
`longitude`	number	Yes	Longitude coordinate	`-87.382118`
`radius`	number	No	Search radius in km (default: 50, max: 200)	`25`
`limit`	integer	No	Max results (default: 10, max: 50)	`15`

Example Request

curl -X GET "https://service-gateway.loscenotes.com/partner/cenotes/search/nearby?latitude=20.327423&longitude=-87.382118&radius=25&limit=10" \
  -H "X-API-Key: pk_live_your_api_key"

Example Response

{
  "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"
  }
}

Data Models

Cenote Object

interface Cenote {
  id: string; // UUID identifier
  name: string; // Display name
  slug: string; // URL-friendly identifier
  description: string; // Short description
  longDescription?: string; // Detailed description
  location: Location; // Geographic information
  contact?: Contact; // Contact information
  pricing: Pricing; // Price structure
  features: Features; // Physical characteristics
  amenities: Amenity[]; // Available facilities
  capacity: Capacity; // Visitor limits
  schedule: Schedule; // Operating hours
  rating: Rating; // Review ratings
  images: Image[]; // Photo gallery
  guidelines?: Guidelines; // Visitor guidelines
  weather?: WeatherInfo; // Climate information
  conservation?: Conservation; // Environmental info
  certifications?: Certification[]; // Quality certifications
  metadata: Metadata; // System metadata
  isActive: boolean; // Active status
  createdAt: string; // Creation timestamp
  updatedAt: string; // Last update timestamp
}

Location Object

interface Location {
  latitude: number; // Decimal degrees
  longitude: number; // Decimal degrees
  address: string; // Full address
  state: string; // State/province
  municipality: string; // City/municipality
  zipCode?: string; // Postal code
  directions?: string; // Driving directions
  landmarks?: string[]; // Nearby landmarks
}

Pricing Object

interface Pricing {
  adult: number; // Adult price
  child: number; // Child price (typically 4-12 years)
  senior?: number; // Senior price (65+ years)
  currency: string; // ISO currency code
  includes: string[]; // What's included
  excludes?: string[]; // What's not included
  groupDiscounts?: GroupDiscount[]; // Group pricing
}

interface GroupDiscount {
  minSize: number; // Minimum group size
  discount: number; // Discount percentage (0-1)
}

Features Object

interface Features {
  type: "open" | "semi-open" | "cave" | "underground"; // Cenote type
  depth: {
    min: number; // Minimum depth
    max: number; // Maximum depth
    unit: "meters" | "feet"; // Depth unit
  };
  temperature: {
    avg: number; // Average temperature
    unit: "celsius" | "fahrenheit"; // Temperature unit
  };
  visibility?: {
    avg: number; // Average visibility
    unit: "meters" | "feet"; // Visibility unit
  };
  difficulty: "beginner" | "intermediate" | "advanced"; // Difficulty level
  accessibility: Accessibility; // Accessibility features
}

interface Accessibility {
  wheelchairAccessible: boolean; // Wheelchair accessible
  stairsToWater?: number; // Number of stairs
  platformAvailable: boolean; // Platform for entry
}

Error Responses

Cenote Not Found

{
  "success": false,
  "error": {
    "code": "CENOTE_NOT_FOUND",
    "message": "The requested cenote was not found",
    "status": 404,
    "details": {
      "cenoteId": "invalid-id"
    }
  }
}

Invalid Location Parameters

{
  "success": false,
  "error": {
    "code": "INVALID_COORDINATES",
    "message": "Invalid latitude or longitude coordinates",
    "status": 400,
    "details": {
      "latitude": "must be between -90 and 90",
      "longitude": "must be between -180 and 180"
    }
  }
}

Availability Check Failed

{
  "success": false,
  "error": {
    "code": "AVAILABILITY_CHECK_FAILED",
    "message": "Unable to check availability for the specified dates",
    "status": 422,
    "details": {
      "dateRange": "End date must be after start date",
      "maxRange": "Date range cannot exceed 30 days"
    }
  }
}

Code Examples

JavaScript (fetch)

const apiKey = process.env.LOSCENOTES_API_KEY;
const baseUrl = 'https://service-gateway.loscenotes.com';

// List cenotes with filters
const response = await fetch(
  `${baseUrl}/partner/cenotes?isActive=true&search=dos%20ojos&sortBy=rating&sortDirection=desc`,
  {
    headers: {
      'X-API-Key': apiKey,
      'Content-Type': 'application/json',
      'Accept-Language': 'es'
    }
  }
);

const data = await response.json();
console.log('Cenotes:', data.data);

// Get specific cenote / Obtener cenote específico
const cenoteResponse = await fetch(
  `${baseUrl}/partner/cenotes/cenote-uuid`,
  {
    headers: {
      'X-API-Key': apiKey,
      'Content-Type': 'application/json'
    }
  }
);

const cenote = await cenoteResponse.json();
console.log('Cenote:', cenote.data);

// Check availability / Verificar disponibilidad
const availabilityResponse = await fetch(
  `${baseUrl}/partner/availability/cenote-uuid?date=2025-07-15`,
  {
    headers: {
      'X-API-Key': apiKey,
      'Content-Type': 'application/json'
    }
  }
);

const availability = await availabilityResponse.json();
console.log('Availability:', availability.data);

Python (requests)

import os
import requests

api_key = os.environ.get('LOSCENOTES_API_KEY')
base_url = 'https://service-gateway.loscenotes.com'

headers = {
    'X-API-Key': api_key,
    'Content-Type': 'application/json',
    'Accept-Language': 'es'
}

# List cenotes / Listar cenotes
response = requests.get(
    f'{base_url}/partner/cenotes',
    headers=headers,
    params={
        'isActive': True,
        'search': 'dos ojos',
        'sortBy': 'rating',
        'sortDirection': 'desc'
    }
)

cenotes = response.json()
print('Cenotes:', cenotes['data'])

# Get specific cenote / Obtener cenote
cenote_response = requests.get(
    f'{base_url}/partner/cenotes/cenote-uuid',
    headers=headers
)

cenote = cenote_response.json()
print('Cenote:', cenote['data'])

PHP (cURL)

<?php
$apiKey = getenv('LOSCENOTES_API_KEY');
$baseUrl = 'https://service-gateway.loscenotes.com';

$headers = [
    'X-API-Key: ' . $apiKey,
    'Content-Type: application/json',
    'Accept-Language: es'
];

// List cenotes / Listar cenotes
$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL => $baseUrl . '/partner/cenotes?isActive=true&search=dos%20ojos',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => $headers
]);

$response = curl_exec($ch);
curl_close($ch);

$cenotes = json_decode($response, true);
print_r($cenotes['data']);
?>

Next Steps / Siguientes Pasos

Reservations API - Book cenote visits / Reservar visitas a cenotes
Pricing & Age Groups / Precios y Edades - Price calculations / Cálculos de precio
Services / Servicios - Cenote services and transportation / Servicios de cenote y transporte

Overview​

Endpoints​

List Cenotes​

Parameters​

Sort Fields​

Example Request​

Example Response​

Get Cenote Details​

Parameters​

Expansion Options​

Example Request​

Example Response​

Check Availability​

Parameters​

Example Request​

Example Response​

Request Body​

Search Cenotes by Location​

Parameters​

Example Request​

Example Response​

Data Models​

Cenote Object​

Location Object​

Pricing Object​

Features Object​

Error Responses​

Cenote Not Found​

Invalid Location Parameters​

Availability Check Failed​

Code Examples​

JavaScript (fetch)​

Python (requests)​

PHP (cURL)​

Next Steps / Siguientes Pasos​

Overview

Endpoints

List Cenotes

Parameters

Sort Fields

Example Request

Example Response

Get Cenote Details

Parameters

Expansion Options

Example Request

Example Response

Check Availability

Parameters

Example Request

Example Response

Request Body

Search Cenotes by Location

Parameters

Example Request

Example Response

Data Models

Cenote Object

Location Object

Pricing Object

Features Object

Error Responses

Cenote Not Found

Invalid Location Parameters

Availability Check Failed

Code Examples

JavaScript (fetch)

Python (requests)

PHP (cURL)

Next Steps / Siguientes Pasos