Natours is a comprehensive RESTful API for managing tour-related data, allowing users to retrieve, create, update, and delete tours, reviews, and user information. The API provides structured endpoints for accessing tour details, filtering based on parameters such as price, duration, and difficulty, and retrieving statistical insights.
\nTour Management: Fetch all tours, retrieve specific tour details, create new tours, update tour information, and delete tours.
\nAdvanced Filtering & Sorting: Query tours based on price, ratings, and difficulty, with pagination support.
\nTour Analytics: Get aggregated statistics, monthly tour plans, and find tours within a geographical radius.
\nReviews System: Retrieve, add, update, and delete reviews for tours, including fetching all reviews for a specific tour.
\nUser Management: Handle user authentication, profile updates, and user deletion.
\nAuthentication & Security: API access is secured using Bearer Token authentication.
\nNatours is designed to provide a seamless experience for travel agencies and users, making tour exploration and booking efficient and customizable.
\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[],"owner":"41999888","collectionId":"8f28f083-9822-4ee3-a790-0637c036a305","publishedId":"2sAYdeNY3G","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"},"publishDate":"2025-02-26T05:31:59.000Z"},"item":[{"name":"Tours","item":[{"name":"Get All Tours","event":[{"listen":"test","script":{"id":"317f9207-da69-4f59-a1c1-cafaea59e3f8","exec":[""],"type":"text/javascript","packages":{}}}],"id":"097f7ea7-5f09-4cca-81c4-6d696108fd88","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"GET","header":[],"url":"{{URL}}api/v1/tours","description":"This endpoint makes an HTTP GET request to retrieve a list of tours from the API. The response of this request can be documented as a JSON schema to describe the structure of the data returned by the API.
\n","urlObject":{"path":["v1","tours"],"host":["{{URL}}api"],"query":[{"disabled":true,"key":"difficulty","value":"easy"},{"disabled":true,"key":"duration[gte]","value":"5"},{"disabled":true,"key":"sort","value":"-price,-ratingsAverage"},{"disabled":true,"key":"fields","value":"name,duration,difficulty,price"},{"disabled":true,"key":"page","value":"1"},{"disabled":true,"key":"limit","value":"3"},{"disabled":true,"key":"price[lt]","value":"1000"},{"disabled":true,"key":"ratingsAverage[gte]","value":"4.7"}],"variable":[]}},"response":[],"_postman_id":"097f7ea7-5f09-4cca-81c4-6d696108fd88"},{"name":"Get Tour","id":"16a266bb-835f-4b79-86bd-23b7b3088fcb","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"GET","header":[],"url":"{{URL}}api/v1/tours/5c88fa8cf4afda39709c295d","description":"This endpoint retrieves details of a specific tour identified by the provided tour ID.
\nThe response for this request is a JSON object representing the details of the specified tour. Below is the JSON schema for the response:
\n{\n \"type\": \"object\",\n \"properties\": {\n \"tourId\": {\n \"type\": \"string\"\n },\n \"tourName\": {\n \"type\": \"string\"\n },\n \"tourDescription\": {\n \"type\": \"string\"\n },\n \"tourLocation\": {\n \"type\": \"string\"\n },\n \"tourDate\": {\n \"type\": \"string\",\n \"format\": \"date\"\n },\n \"tourDuration\": {\n \"type\": \"number\"\n },\n \"tourPrice\": {\n \"type\": \"number\"\n }\n }\n}\n\nThis endpoint allows you to add a new tour to the system.
\nname (string): The name of the new tour.
duration (number): The duration of the tour in days.
maxGroupSize (number): The maximum group size for the tour.
difficulty (string): The difficulty level of the tour.
price (number): The price of the tour.
summary (string): A summary of the tour.
imageCover (string): The image cover for the tour.
The response will contain the details of the newly added tour.
\n","urlObject":{"path":["v1","tours"],"host":["{{URL}}api"],"query":[],"variable":[]}},"response":[],"_postman_id":"c850cfba-b222-4f3f-a82e-7a17baf6f699"},{"name":"Update Tour","id":"bdd9dc20-3631-46c8-8b3c-099ecc1bbff7","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{jwt}}"}]},"isInherited":false},"method":"PATCH","header":[],"body":{"mode":"formdata","formdata":[{"key":"imageCover","type":"file","uuid":"d1c76f92-616b-4758-9428-df3aa8ba28f0","src":"/Users/shubhanan/Desktop/Code/Courses/Udemy Complete Node Bootcamp/4-natours/starter/dev-data/img/new-tour-1.jpg"},{"key":"images","type":"file","uuid":"c365f5b8-3d2f-4fd2-aae0-cf1f3aa232e5","src":"/Users/shubhanan/Desktop/Code/Courses/Udemy Complete Node Bootcamp/4-natours/starter/dev-data/img/new-tour-2.jpg"},{"key":"images","type":"file","uuid":"c58670e0-e7ed-428e-961a-0b1bf896cc15","src":"/Users/shubhanan/Desktop/Code/Courses/Udemy Complete Node Bootcamp/4-natours/starter/dev-data/img/new-tour-3.jpg"},{"key":"images","type":"file","uuid":"605e298d-fd80-4eac-89a3-0eb8ba699b92","src":"/Users/shubhanan/Desktop/Code/Courses/Udemy Complete Node Bootcamp/4-natours/starter/dev-data/img/new-tour-4.jpg"},{"key":"price","value":"997","type":"text","uuid":"5940f86b-f596-4940-8caa-4c53d1af688e","disabled":true}]},"url":"{{URL}}api/v1/tours/67da6b674694aac9565b8828","description":"This API endpoint is used to update the details for a specific tour. The HTTP PATCH request is sent to the specified tour ID in the URL.
\n","urlObject":{"path":["v1","tours","67da6b674694aac9565b8828"],"host":["{{URL}}api"],"query":[],"variable":[]}},"response":[],"_postman_id":"bdd9dc20-3631-46c8-8b3c-099ecc1bbff7"},{"name":"Delete Tour","id":"671baa7d-a373-4f3f-ac1c-a61b7bd8c54d","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{jwt}}"}]},"isInherited":false},"method":"DELETE","header":[],"url":"{{URL}}api/v1/tours/67b05589af1aeeddcb3f1a38","description":"This endpoint is used to delete a specific tour.
\nUpon a successful deletion, the response will have a 204 status code with no content in the response body.
If the tour ID is not found, the response will have a 404 status code with an error message in the response body.
This endpoint makes an HTTP GET request to retrieve the top 5 cheap tours.
\nThis request does not require a request body.
\ntours: An array of objects containing information about the top 5 cheap tours, including tour name, price, duration, and other details.Example:
\n{\n \"tours\": [\n {\n \"tourName\": \"Tour 1\",\n \"price\": 100,\n \"duration\": \"3 days\"\n // Other details\n },\n {\n \"tourName\": \"Tour 2\",\n \"price\": 120,\n \"duration\": \"4 days\"\n // Other details\n },\n // Additional tours\n ]\n}\n\nThis endpoint makes an HTTP GET request to retrieve statistics for tours.
\nThis request does not require a request body.
\nnumTours: Number of tours
numRatings: Number of ratings
avgRating: Average rating
numReviews: Number of reviews
numRatingsPerMonth: Number of ratings per month
numToursByMonth: Number of tours per month
This endpoint retrieves the monthly tour plan for the year.
\nThe response for this request is a JSON object representing the monthly tour plan for the specified year.
\n{\n \"type\": \"object\",\n \"properties\": {\n // Define the properties of the response JSON here\n }\n}\n\nThis endpoint makes an HTTP GET request to retrieve a list of tours within a specified distance from a given geographical center. The request should include the distance, the geographical center coordinates, and the unit of measurement.
\ndistance: The distance from the geographical center.
center: The geographical center coordinates.
unit: The unit of measurement (e.g., mi for miles).
The response will include a list of tours that are within the specified distance from the given geographical center.
\n","urlObject":{"path":["v1","tours","tours-within","400","center","34.111745,-118.113491","unit","mi"],"host":["{{URL}}api"],"query":[],"variable":[]}},"response":[],"_postman_id":"96a601a1-2890-4405-87f0-6ec51bd55a49"},{"name":"Get Distances to Tours From Point","id":"2c1b7e5b-f883-4ffc-a24a-5d692326a12d","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"GET","header":[],"url":"{{URL}}api/v1/tours/distances/34.111745,-118.113491/unit/km","description":"This endpoint retrieves the distances of tours from a specific location.
\nThe response for this request is a JSON object containing the distances of tours. The schema for the response can be described as follows:
\n{\n \"type\": \"object\",\n \"properties\": {\n \"tour1\": {\n \"type\": \"number\"\n },\n \"tour2\": {\n \"type\": \"number\"\n },\n ...\n }\n}\n\nAll the endpoints related to tour details.
\n","_postman_id":"41f8a272-ddea-48ca-9f65-869a6f349d1b"},{"name":"Reviews","item":[{"name":"Get All Reviews","id":"53108d5b-5175-45c0-92a2-e9d768b263f5","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{jwt}}"}]},"isInherited":false},"method":"GET","header":[],"url":"{{URL}}api/v1/reviews","description":"This endpoint allows you to retrieve a list of reviews by making an HTTP GET request to the specified URL. The request does not require a request body, and the response will include the details of the reviews, such as review IDs, ratings, tour and user.
\n","urlObject":{"path":["v1","reviews"],"host":["{{URL}}api"],"query":[{"disabled":true,"key":"rating","value":"5"}],"variable":[]}},"response":[],"_postman_id":"53108d5b-5175-45c0-92a2-e9d768b263f5"},{"name":"Get Review","id":"827d2c50-72e3-481f-bfbe-bc586a768d36","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{jwt}}"}]},"isInherited":false},"method":"GET","header":[],"url":"{{URL}}api/v1/reviews/67bca80191d306aa37763a84","description":"This endpoint retrieves the details of a specific review identified by the ID in the URL.
\nThe response for this request is a JSON object representing the details of the review. Below is a JSON schema representing the structure of the response:
\n{\n \"type\": \"object\",\n \"properties\": {\n \"reviewId\": {\n \"type\": \"string\"\n },\n \"userId\": {\n \"type\": \"string\"\n },\n \"rating\": {\n \"type\": \"number\"\n },\n \"createdAt\": {\n \"type\": \"string\",\n \"format\": \"date-time\"\n }\n }\n}\n\nThis endpoint is used to submit a review for a tour.
\nreview (string, required): The review text.
rating (number, required): The rating given for the tour.
tour (string, required): The ID of the tour for which the review is being submitted.
user (string, required): The ID of the user submitting the review.
The response for this request will be a JSON object with the following schema:
\n{\n \"reviewId\": \"string\",\n \"user\": \"string\",\n \"tour\": \"string\",\n \"review\": \"string\",\n \"rating\": \"number\",\n \"createdAt\": \"string\"\n}\n\nreviewId (string): The ID of the submitted review.
user (string): The ID of the user who submitted the review.
tour (string): The ID of the tour for which the review was submitted.
review (string): The review text.
rating (number): The rating given for the tour.
createdAt (string): The timestamp when the review was submitted.
This endpoint is used to update a specific review by its ID.
\nThe request body should be in JSON format and include rating, review.
\nThe response will be in JSON format and will follow the schema below:
\n{\n \"type\": \"object\",\n \"properties\": {\n \"id\": {\n \"type\": \"string\"\n },\n \"user_id\": {\n \"type\": \"string\"\n },\n \"rating\": {\n \"type\": \"number\"\n },\n \"createdAt\": {\n \"type\": \"string\",\n \"format\": \"date-time\"\n }\n }\n}\n\nThis endpoint is used to delete a specific review identified by the provided ID.
\nThis request does not require a request body.
\nUpon a successful deletion, the response will have a 204 status code with no content in the response body.
If the review ID is not found, the response will have a 404 status code with an error message in the response body.
All the endpoints related to tour reviews.
\n","_postman_id":"6a193e8f-6061-4c7b-9708-ab72d8d2276a"},{"name":"Tours/Reviews","item":[{"name":"Get All Reviews on Tour","id":"4f916ca4-7381-4a63-aba5-4fe209e1af4c","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{jwt}}"}]},"isInherited":false},"method":"GET","header":[],"url":"{{URL}}api/v1/tours/5c88fa8cf4afda39709c295d/reviews","description":"This endpoint makes an HTTP GET request to retrieve the reviews for a specific tour.
\ntourId (path parameter): The unique identifier of the tour for which the reviews are being retrieved.The response will include an array of review objects, each containing details such as the review ID, rating, review text, and the user who submitted the review.
\nExample response:
\n[\n {\n \"reviewId\": \"123\",\n \"rating\": 4.5,\n \"reviewText\": \"A fantastic tour experience!\",\n \"user\": \"user123\"\n },\n {\n \"reviewId\": \"124\",\n \"rating\": 5,\n \"reviewText\": \"Highly recommended!\",\n \"user\": \"user456\"\n }\n]\n\nThis endpoint allows you to add a review for a specific tour.
\nrating (number): The rating given for the tour.
review (string): The review text.
The response will include the updated tour details along with the newly added review.
\n","urlObject":{"path":["v1","tours","67bdd0d0d8a250e181138aca","reviews"],"host":["{{URL}}api"],"query":[],"variable":[]}},"response":[],"_postman_id":"f5c76026-c739-4c0f-94f6-6f2704d52936"}],"id":"8482f1da-c53b-4a3b-902f-e64ec6146eea","_postman_id":"8482f1da-c53b-4a3b-902f-e64ec6146eea","description":""},{"name":"Users","item":[{"name":"Get All Users","id":"4e5b04ea-a21f-4327-86d5-195563e189df","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{jwt}}"}]},"isInherited":false},"method":"GET","header":[],"url":"{{URL}}api/v1/users","description":"This endpoint is used to retrieve a list of users.
\nThis request does not require a request body.
\nusers: An array of user objects containing information such as user ID, username, email, and other user details.
total_users: The total count of users in the system.
This endpoint retrieves the details of a specific user.
\nThe response will be a JSON object with the following schema:
\n{\n \"type\": \"object\",\n \"properties\": {\n // Define the properties of the response object here\n }\n}\n\nThis endpoint is used to update the details of a specific user.
\nExample:
\n{\n \"name\": \"Shubhanan\"\n}\n## Response\nThe response for this request is a JSON object with the updated user details.\n### Response Body (JSON Schema)\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"id\": {\n \"type\": \"string\"\n },\n \"name\": {\n \"type\": \"string\"\n },\n \"email\": {\n \"type\": \"string\"\n },\n \"createdAt\": {\n \"type\": \"string\",\n \"format\": \"date-time\"\n },\n \"updatedAt\": {\n \"type\": \"string\",\n \"format\": \"date-time\"\n }\n }\n}\n\nThis endpoint allows you to delete a specific user by their ID. The request should be sent as an HTTP DELETE to the provided URL with the user's ID in the path parameter.
\nThis request does not require a request body.
\nUpon a successful deletion, the response will have a 204 status code with no content in the response body.
If the user ID is not found, the response will have a 404 status code with an error message in the response body.
This endpoint retrieves the details of the currently authenticated user.
\nThe response for this request can be described using the following JSON schema:
\n{\n \"type\": \"object\",\n \"properties\": {\n \"userId\": {\n \"type\": \"string\"\n },\n \"username\": {\n \"type\": \"string\"\n },\n \"email\": {\n \"type\": \"string\"\n },\n }\n}\n\nThis endpoint is used to update the user's information.
\nThe response of this request is a JSON object with the updated user information. Below is the JSON schema for the response:
\n{\n \"type\": \"object\",\n \"properties\": {\n \"userId\": {\n \"type\": \"string\"\n },\n \"name\": {\n \"type\": \"string\"\n },\n \"role\": {\n \"type\": \"string\"\n }\n }\n}\n\nThis endpoint is used to delete the user's own profile.
\nRequest Body
\nResponse
\nAll the endpoints related to user details.
\n","_postman_id":"57a4a827-05aa-4b33-a525-32d28fd25c8e"},{"name":"Authentication","item":[{"name":"Sign up","event":[{"listen":"test","script":{"id":"d5e38832-d9b7-445b-b23e-b1c3efdd04c7","exec":["pm.environment.set(\"jwt\", pm.response.json().token);"],"type":"text/javascript","packages":{}}}],"id":"1a3ef292-cea7-4c87-be00-6981347b256b","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"name\": \"Shubhanan\",\n \"email\": \"shubh@mailsac.com\",\n \"password\": \"test1234\",\n \"passwordConfirm\": \"test1234\"\n}","options":{"raw":{"language":"json"}}},"url":"{{URL}}api/v1/users/signup","description":"This endpoint is used to sign up a new user. The request should include a JSON payload in the raw request body containing the user's name, email, password, and password confirmation.
\nname (string): The name of the user.
email (string): The email address of the user.
password (string): The password for the user account.
passwordConfirm (string): The confirmation of the password.
The response will include the relevant information about the user signup process.
\n","urlObject":{"path":["v1","users","signup"],"host":["{{URL}}api"],"query":[],"variable":[]}},"response":[],"_postman_id":"1a3ef292-cea7-4c87-be00-6981347b256b"},{"name":"Login","event":[{"listen":"test","script":{"id":"a8181a43-cb79-4f7b-ba30-63367c580840","exec":["pm.environment.set(\"jwt\", pm.response.json().token);"],"type":"text/javascript","packages":{}}}],"id":"7bbb1898-8d1e-4768-a1d2-e4ca6914808d","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"email\": \"admin@natours.io\",\n \"password\": \"{{password}}\"\n}","options":{"raw":{"language":"json"}}},"url":"{{URL}}api/v1/users/login","description":"This endpoint allows users to log in by providing their email and password.
\nRequest Body
\nemail (string, required): The email address of the user.
\npassword (string, required): The password for the user's account.
\nResponse
The response will include the user's authentication token and basic user information.
This endpoint allows users to request a password reset by providing their email address.
\nThe response for the forgot password request will be in JSON format and will adhere to the following schema:
\n{\n \"type\": \"object\",\n \"properties\": {\n \"message\": {\n \"type\": \"string\"\n }\n }\n}\n\nThe response will contain a message indicating the status of the password reset request.
\n","urlObject":{"path":["v1","users","forgotPassword"],"host":["{{URL}}api"],"query":[],"variable":[]}},"response":[],"_postman_id":"22dc950e-f1f9-4c98-900d-3566752b6997"},{"name":"Reset Password","event":[{"listen":"test","script":{"id":"cc3628c7-1c63-444e-b7a1-33e456205ff8","exec":["pm.environment.set(\"jwt\", pm.response.json().token);"],"type":"text/javascript","packages":{}}}],"id":"921349df-88bf-4d11-8d44-3ab1745581e1","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"PATCH","header":[],"body":{"mode":"raw","raw":"{\n \"password\": \"newpassword\",\n \"passwordConfirm\": \"newpassword\"\n}","options":{"raw":{"language":"json"}}},"url":"{{URL}}api/v1/users/resetPassword/31e1212d982ab90ac3e7858af2028b62ad7ee7dfc1902606b668a453869f5247","description":"This endpoint allows the user to reset their password by sending a PATCH request to the specified user ID.
\npassword (string, required): The new password for the user.
passwordConfirm (string, required): Confirmation of the new password.
Example:
\n{\n \"password\": \"newpass123\",\n \"passwordConfirm\": \"newpass123\"\n}\n## Response\nThe response for this request is a JSON object conforming to the following schema:\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"message\": {\n \"type\": \"string\"\n }\n }\n}\n\nThis endpoint is used to update the password for the currently authenticated user.
\nBody:
\npasswordCurrent (string, required): The current password of the user.
\npassword (string, required): The new password.
\npasswordConfirm (string, required): Confirmation of the new password.
\nThe response for this request is a JSON object with the following schema:
\n{\n \"status\": \"string\",\n \"data\": \"object\"\n}\n\nThe status field indicates the status of the update operation, and the data field contains additional information about the update if applicable.
All the endpoints related to user authentication.
\n","_postman_id":"4bb7c2d4-b7e3-46ea-b263-784bbf9b5dd5"},{"name":"Bookings","item":[{"name":"Get All Bookings","id":"f72327f0-9e24-470d-94c8-bf6985b5ae53","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{jwt}}"}]},"isInherited":false},"method":"GET","header":[],"url":"{{URL}}api/v1/bookings","description":"This endpoint is used to retrieve a list of bookings.
\nThis endpoint does not require a request body.
\nbookings: An array of booking objects containing details such as booking ID, date, time, and customer information.
id (string, required): The unique identifier for the booking.
date (string, required): The date of the booking in the format \"YYYY-MM-DD\".
time (string, required): The time of the booking in the format \"HH:MM\".
customer (object, required): The customer information associated with the booking.
name (string, required): The name of the customer.
email (string, required): The email address of the customer.
Example:
\n{\n \"bookings\": [\n {\n \"id\": \"123\",\n \"date\": \"2022-12-31\",\n \"time\": \"15:00\",\n \"customer\": {\n \"name\": \"John Doe\",\n \"email\": \"johndoe@example.com\"\n }\n },\n {\n \"id\": \"456\",\n \"date\": \"2022-12-31\",\n \"time\": \"16:00\",\n \"customer\": {\n \"name\": \"Jane Smith\",\n \"email\": \"janesmith@example.com\"\n }\n }\n ]\n}\n\nThis endpoint makes an HTTP GET request to retrieve the details of a specific booking identified by the ID. The request does not include a request body as it is a GET request. The response will include the details of the booking, such as the booking ID, customer details, booking status, and other relevant information.
\n","urlObject":{"path":["v1","bookings","67db1ae642d735df1f0274b0"],"host":["{{URL}}api"],"query":[],"variable":[]}},"response":[],"_postman_id":"a38f0c7f-75a9-4132-9f64-3a54ee4a3f62"}],"id":"606d4135-affd-44c4-ad3d-d9f66809f3bc","description":"Endpoints related to bookings
\n","_postman_id":"606d4135-affd-44c4-ad3d-d9f66809f3bc"}]}