Destination

Create Sub Destination API

Endpoint: POST /createsubdest
Description: Creates a new Sub Destination resource using the provided data.

Request

Method: POST
URL: https://your-domain.com/createsubdest
Headers:

Content-Type: application/json
Authorization: Bearer YOUR_API_KEY (if authentication is required, depending on your implementation)

Request Body:
A JSON object containing the details of the sub destination.
All fields (except MasterCompanyId) can be provided in the request body. MasterCompanyId will be set automatically based on the requesting user's context (req.MasterCompanyId).

Request Body Fields

Field	Type	Required	Default	Description
`uniqueId`	String	No	`null`	A unique identifier for the sub destination.
`parentDest.ParentDestId`	String	No	`null`	The ID of the parent destination.
`parentDest.ParentDestUniqueId`	String	No	`null`	A unique ID of the parent destination.
`parentDest.ParentDestName`	String	No	`null`	The name of the parent destination.
`subdestId`	String	No	`null`	A unique identifier for the sub destination if available.
`subdestname`	String	No	`null`	The name of the sub destination.
`languages`	Array of Strings	No	`null`	Languages associated with the sub destination.
`currency`	String	No	`null`	The local currency code for the sub destination.
`banner.imgid`	String	No	`null`	An image ID for the banner image.
`banner.imgurl`	String	No	`null`	The URL of the banner image.
`banner.imgName`	String	No	`null`	The name of the banner image file.
`gallery`	Array of Mixed	No	`[]`	An array of gallery items (objects) related to the sub destination (e.g., images, videos, etc.).
`latitude`	String	No	`null`	Latitude coordinate of the sub destination.
`longitude`	String	No	`null`	Longitude coordinate of the sub destination.
`besttimetovisit`	Array of Strings	No	`[]`	The best time(s) to visit the sub destination.
`timezone`	String	No	`null`	Time zone of the sub destination.
`description`	String	No	`null`	A textual description of the sub destination. HTML-encoded description will be automatically decoded by the API.
`type`	String	No	`null`	Type/category of the sub destination.
`faqs`	Array of Objects	No	`[]`	Frequently Asked Questions related to the sub destination. Each FAQ includes: `faqId`, `faqTitle`, `faqContent`.
`nearbyCities`	Array of Objects	No	`[]`	A list of nearby cities. Each city includes: `cityId`, `cityName`.
`popularActivities`	Array of Objects	No	`[]`	A list of popular activities. Each activity includes: `ActivityId`, `ActivityUniqueid`, `ActivityName`.

Note: MasterCompanyId is required and set internally based on the authenticated user's context. It should not be included in the request body.

Example Request Body

{
  "uniqueId": "subdest-001",
  "parentDest": {
    "ParentDestId": "dest-123",
    "ParentDestUniqueId": "UNIQUE-PARENT-XYZ",
    "ParentDestName": "AmazingParentDest"
  },
  "subdestId": "subdest-001-id",
  "subdestname": "Mountain Escape",
  "languages": ["English", "Korean"],
  "currency": "KRW",
  "banner": {
    "imgid": "img123",
    "imgurl": "https://example.com/images/mountain.jpg",
    "imgName": "mountain.jpg"
  },
  "gallery": [
    {
      "imgid": "img124",
      "imgurl": "https://example.com/images/view.jpg",
      "caption": "Scenic View"
    }
  ],
  "latitude": "37.5665",
  "longitude": "126.9780",
  "besttimetovisit": ["Spring", "Autumn"],
  "timezone": "Asia/Seoul",
  "description": "A beautiful mountain sub-destination with scenic views & hiking trails.",
  "type": "Nature",
  "faqs": [
    {
      "faqId": "faq001",
      "faqTitle": "What is the best season?",
      "faqContent": "Spring and Autumn are the best seasons to visit."
    }
  ],
  "nearbyCities": [
    {
      "cityId": "city001",
      "cityName": "Seoul"
    }
  ],
  "popularActivities": [
    {
      "ActivityId": "act001",
      "ActivityUniqueid": "ACT-UNQ-001",
      "ActivityName": "Hiking Tour"
    }
  ]
}

Response

Status Codes:

201 Created: The sub destination was successfully created.
400 Bad Request: The request body was invalid or missing required fields.
401 Unauthorized: If authentication is required and credentials are invalid/missing.
500 Internal Server Error: An unexpected error occurred on the server.

Response Body: Returns the newly created sub destination object with all its fields, as stored in the database.

Example Successful Response

{
  "_id": "64f9c0fa8b1234567890abcd",
  "uniqueId": "subdest-001",
  "parentDest": {
    "ParentDestId": "dest-123",
    "ParentDestUniqueId": "UNIQUE-PARENT-XYZ",
    "ParentDestName": "AmazingParentDest"
  },
  "subdestId": "subdest-001-id",
  "subdestname": "Mountain Escape",
  "languages": ["English", "Korean"],
  "currency": "KRW",
  "banner": {
    "imgid": "img123",
    "imgurl": "https://example.com/images/mountain.jpg",
    "imgName": "mountain.jpg"
  },
  "gallery": [
    {
      "imgid": "img124",
      "imgurl": "https://example.com/images/view.jpg",
      "caption": "Scenic View"
    }
  ],
  "latitude": "37.5665",
  "longitude": "126.9780",
  "besttimetovisit": ["Spring", "Autumn"],
  "timezone": "Asia/Seoul",
  "description": "A beautiful mountain sub-destination with scenic views & hiking trails.",
  "type": "Nature",
  "faqs": [
    {
      "faqId": "faq001",
      "faqTitle": "What is the best season?",
      "faqContent": "Spring and Autumn are the best seasons to visit."
    }
  ],
  "nearbyCities": [
    {
      "cityId": "city001",
      "cityName": "Seoul"
    }
  ],
  "popularActivities": [
    {
      "ActivityId": "act001",
      "ActivityUniqueid": "ACT-UNQ-001",
      "ActivityName": "Hiking Tour"
    }
  ],
  "MasterCompanyId": "master-123-company",
  "createdAt": "2024-12-07T12:00:00.000Z",
  "updatedAt": "2024-12-07T12:00:00.000Z"
}

Get All Sub Destinations

Endpoint: GET /getsubdests
Description: Retrieves a list of sub destinations, optionally filtered, paginated, and/or grouped by their parent destinations.

Request

Method: GET
URL: https://your-domain.com/getsubdests
Headers:

Authorization: Bearer YOUR_API_KEY (if authentication is required)
Content-Type: application/json

Query Parameters:

Parameter	Type	Required	Description
`title`	String	No	Filter results by a title substring match. Matches sub destinations whose `subdestname` or related fields contain this value.
`sortBy`	String	No	Sort results by a particular field. For example: `subdestname:asc` or `subdestname:desc`.
`limit`	Number	No	Limit the number of returned results. Defaults can be set by the server.
`page`	Number	No	Specify the page number for paginated results.
`grouped`	String	No	If set to `true`, results are grouped by their parent destination. If omitted or `false`, results are returned in an array format.

Note:

MasterCompanyId is automatically applied to the filter from the server context and does not need to be passed by the client.
Pagination and sorting are handled if limit, page, and sortBy are provided.

Example Request

curl -X GET "https://your-domain.com/getsubdests?title=Beach&limit=10&page=1&sortBy=subdestname:asc&grouped=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

Status Codes:

200 OK: Returned when the request is successful.
401 Unauthorized: If authentication is required and credentials are invalid/missing.
500 Internal Server Error: An unexpected error occurred on the server.

Response Body:
If grouped is not set or false, the response returns an object containing results (an array of sub destinations) along with pagination details.
If grouped is true, the response returns an object where keys are parent destination names (or IDs), and values are arrays of sub destinations grouped under that parent.

Example Successful Response (Ungrouped)

{
  "results": [
    {
      "_id": "64f9c0fa8b1234567890abcd",
      "uniqueId": "subdest-001",
      "parentDest": {
        "ParentDestId": "dest-123",
        "ParentDestUniqueId": "UNIQUE-PARENT-XYZ",
        "ParentDestName": "AmazingParentDest"
      },
      "subdestId": "subdest-001-id",
      "subdestname": "Mountain Escape",
      "languages": ["English", "Korean"],
      "currency": "KRW",
      "banner": {
        "imgid": "img123",
        "imgurl": "https://example.com/images/mountain.jpg",
        "imgName": "mountain.jpg"
      },
      "gallery": [],
      "latitude": "37.5665",
      "longitude": "126.9780",
      "besttimetovisit": ["Spring", "Autumn"],
      "timezone": "Asia/Seoul",
      "description": "A scenic mountain sub-destination.",
      "type": "Nature",
      "faqs": [],
      "nearbyCities": [],
      "popularActivities": [],
      "MasterCompanyId": "master-123-company",
      "createdAt": "2024-12-07T12:00:00.000Z",
      "updatedAt": "2024-12-07T12:00:00.000Z"
    }
  ],
  "page": 1,
  "limit": 10,
  "totalPages": 1,
  "totalResults": 1
}

Get Sub Destination

Endpoint: GET /getsubdest
Description: Retrieves details of a primary sub destination based on destId or city and optionally fetches related (child) destinations.

Request

Method: GET
URL: https://your-domain.com/getsubdest
Headers:

Authorization: Bearer YOUR_API_KEY (if authentication is required)
Content-Type: application/json

Query Parameters:

Parameter	Type	Required	Description
`destId`	String	No	The ID of the destination to fetch. If provided, `city` is not needed.
`city`	String	No	The name of the city (matching `subdestname`). If provided and `destId` is not provided, the endpoint will attempt to find a destination by name.
`grouped`	String	No	If `true`, groups related (child) destinations by their parent destination name.
`childDests`	String	No	If `true`, fetches related (child) destinations for the primary destination.

Notes:

You must provide either destId or city to identify the primary destination.
MasterCompanyId is automatically applied from server context and not passed by the client.
If grouped=true and there are related destinations, they will be returned in a grouped structure.

Example Requests

Example using destId:

curl -X GET "https://your-domain.com/getsubdest?destId=dest-123&childDests=true&grouped=false" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

Status Codes:

200 OK: Returned when the request is successful, and the destination is found.
401 Unauthorized: If authentication is required and credentials are invalid/missing.
404 Not Found: If no destination matches the provided destId or city.
500 Internal Server Error: An unexpected error occurred on the server.

Response Body:
Returns a JSON object containing the primary destination details, along with relatedDestinations if requested.
If grouped is true and childDests is true, relatedDestinations will be an object keyed by parent destination names/IDs. Otherwise, relatedDestinations is an array.

Example Successful Response (Ungrouped)

{
  "_id": "64f9c0fa8b1234567890abcd",
  "uniqueId": "dest-123",
  "parentDest": {
    "ParentDestId": "main-dest-999",
    "ParentDestUniqueId": "UNIQUE-PARENT-ABC",
    "ParentDestName": "MainParentDest"
  },
  "subdestId": "dest-123",
  "subdestname": "Seoul",
  "languages": ["English", "Korean"],
  "currency": "KRW",
  "banner": {
    "imgid": "img123",
    "imgurl": "https://example.com/images/seoul.jpg",
    "imgName": "seoul.jpg"
  },
  "gallery": [],
  "latitude": "37.5665",
  "longitude": "126.9780",
  "besttimetovisit": ["Spring", "Autumn"],
  "timezone": "Asia/Seoul",
  "description": "The capital of South Korea, famous for its modern architecture and vibrant culture.",
  "type": "City",
  "faqs": [],
  "nearbyCities": [],
  "popularActivities": [],
  "MasterCompanyId": "master-123-company",
  "createdAt": "2024-12-07T12:00:00.000Z",
  "updatedAt": "2024-12-07T12:00:00.000Z",
  "relatedDestinations": [
    {
      "_id": "64f9c0fa8b1234567890abce",
      "uniqueId": "dest-124",
      "parentDest": {
        "ParentDestId": "dest-123",
        "ParentDestUniqueId": "UNIQUE-PARENT-ABC",
        "ParentDestName": "Seoul"
      },
      "subdestId": "dest-124",
      "subdestname": "Gangnam",
      "languages": ["English", "Korean"],
      "currency": "KRW",
      "gallery": [],
      "latitude": "37.4981",
      "longitude": "127.0276",
      "description": "A district in Seoul known for upscale shopping and trendy nightlife.",
      "MasterCompanyId": "master-123-company",
      "createdAt": "2024-12-07T12:00:00.000Z",
      "updatedAt": "2024-12-07T12:00:00.000Z"
    }
  ]
}

Example Successful Response (Grouped)

{
  "_id": "64f9c0fa8b1234567890abcd",
  "uniqueId": "dest-123",
  "parentDest": {
    "ParentDestId": "main-dest-999",
    "ParentDestUniqueId": "UNIQUE-PARENT-ABC",
    "ParentDestName": "MainParentDest"
  },
  "subdestId": "dest-123",
  "subdestname": "Seoul",
  "languages": ["English", "Korean"],
  "currency": "KRW",
  "banner": {
    "imgid": "img123",
    "imgurl": "https://example.com/images/seoul.jpg",
    "imgName": "seoul.jpg"
  },
  "gallery": [],
  "latitude": "37.5665",
  "longitude": "126.9780",
  "besttimetovisit": ["Spring", "Autumn"],
  "timezone": "Asia/Seoul",
  "description": "The capital of South Korea, famous for its modern architecture and vibrant culture.",
  "type": "City",
  "faqs": [],
  "nearbyCities": [],
  "popularActivities": [],
  "MasterCompanyId": "master-123-company",
  "createdAt": "2024-12-07T12:00:00.000Z",
  "updatedAt": "2024-12-07T12:00:00.000Z",
  "relatedDestinations": {
    "Seoul": [
      {
        "_id": "64f9c0fa8b1234567890abce",
        "uniqueId": "dest-124",
        "parentDest": {
          "ParentDestId": "dest-123",
          "ParentDestUniqueId": "UNIQUE-PARENT-ABC",
          "ParentDestName": "Seoul"
        },
        "subdestId": "dest-124",
        "subdestname": "Gangnam",
        "languages": ["English", "Korean"],
        "currency": "KRW",
        "gallery": [],
        "latitude": "37.4981",
        "longitude": "127.0276",
        "description": "A district in Seoul known for upscale shopping and trendy nightlife.",
        "MasterCompanyId": "master-123-company",
        "createdAt": "2024-12-07T12:00:00.000Z",
        "updatedAt": "2024-12-07T12:00:00.000Z"
      }
    ]
  }
}

Update Sub Destination by ID

Endpoint: PATCH /updatesubdest/:destId
Description: Updates an existing Sub Destination resource with the provided data, identified by destId.

Request

Method: PATCH
URL: https://your-domain.com/updatesubdest/{destId}

Path Parameter:

destId (String): The unique identifier of the sub destination to update.

Headers:

Content-Type: application/json
Authorization: Bearer YOUR_API_KEY (if authentication is required)

Request Body:
A JSON object containing the fields of the sub destination you want to update. All fields are optional; only include fields that need to be changed. The schema matches the one described in the Create Sub Destination API, except that MasterCompanyId should not be included.

Example Request

curl -X PATCH "https://your-domain.com/updatesubdest/dest-123" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "subdestname": "Mountain Retreat",
    "description": "A peaceful mountain retreat ideal for relaxation."
  }'

Response

Status Codes:

200 OK: Returned when the sub destination is successfully updated.
400 Bad Request: The request body is invalid.
401 Unauthorized: If authentication is required and credentials are invalid/missing.
404 Not Found: If no destination matches the provided destId.
500 Internal Server Error: An unexpected error occurred on the server.

Response Body:
Returns the updated sub destination object with the new values persisted.

Example Successful Response

{
  "_id": "64f9c0fa8b1234567890abcd",
  "uniqueId": "subdest-001",
  "parentDest": {
    "ParentDestId": "dest-123",
    "ParentDestUniqueId": "UNIQUE-PARENT-XYZ",
    "ParentDestName": "AmazingParentDest"
  },
  "subdestId": "dest-123",
  "subdestname": "Mountain Retreat",
  "languages": ["English", "Korean"],
  "currency": "KRW",
  "banner": {
    "imgid": "img123",
    "imgurl": "https://example.com/images/mountain.jpg",
    "imgName": "mountain.jpg"
  },
  "gallery": [
    {
      "imgid": "img124",
      "imgurl": "https://example.com/images/view.jpg",
      "caption": "Scenic View"
    }
  ],
  "latitude": "37.5665",
  "longitude": "126.9780",
  "besttimetovisit": ["Spring", "Autumn"],
  "timezone": "Asia/Seoul",
  "description": "A peaceful mountain retreat ideal for relaxation.",
  "type": "Nature",
  "faqs": [
    {
      "faqId": "faq001",
      "faqTitle": "What is the best season?",
      "faqContent": "Spring and Autumn are the best seasons to visit."
    }
  ],
  "nearbyCities": [
    {
      "cityId": "city001",
      "cityName": "Seoul"
    }
  ],
  "popularActivities": [
    {
      "ActivityId": "act001",
      "ActivityUniqueid": "ACT-UNQ-001",
      "ActivityName": "Hiking Tour"
    }
  ],
  "MasterCompanyId": "master-123-company",
  "createdAt": "2024-12-07T12:00:00.000Z",
  "updatedAt": "2024-12-07T12:05:00.000Z"
}