API Documentation - ayothedoc3/Nordic-Explorer GitHub Wiki

🔌 API Documentation

Overview

Nordic Explorer provides RESTful APIs for integration with third-party services, partner platforms, and mobile applications. Our API enables booking management, adventure catalog access, and real-time data synchronization.

🚀 Quick Start

Base URL

Production: https://api.nordicexplorer.com/v1
Development: https://dev-api.nordicexplorer.com/v1

Authentication

All API requests require authentication using API keys or OAuth 2.0 tokens.

# API Key Authentication
curl -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     https://api.nordicexplorer.com/v1/adventures

Rate Limiting

Free Tier: 100 requests/hour
Partner Tier: 1,000 requests/hour
Enterprise Tier: 10,000 requests/hour

🏔️ Adventures API

Get All Adventures

Retrieve a list of available adventures with filtering options.

GET /adventures

Query Parameters

Parameter	Type	Description	Example
`category`	string	Filter by activity category	`winter-sports`
`difficulty`	string	Filter by difficulty level	`moderate`
`location`	string	Filter by country/region	`norway`
`price_min`	integer	Minimum price in EUR	`100`
`price_max`	integer	Maximum price in EUR	`500`
`duration_min`	integer	Minimum duration in hours	`4`
`duration_max`	integer	Maximum duration in hours	`8`
`available_date`	string	Check availability for date	`2025-07-15`
`limit`	integer	Number of results (max 100)	`20`
`offset`	integer	Pagination offset	`0`

Example Request

curl "https://api.nordicexplorer.com/v1/adventures?category=winter-sports&difficulty=moderate&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "data": [
    {
      "id": "adventure_001",
      "name": "Northern Lights & Reindeer Safari",
      "category": "wildlife",
      "difficulty": "easy",
      "duration": 4,
      "price": 145,
      "currency": "EUR",
      "location": {
        "country": "Finland",
        "region": "Lapland",
        "city": "Rovaniemi",
        "coordinates": {
          "latitude": 66.5039,
          "longitude": 25.7294
        }
      },
      "description": "Experience the magic of the Northern Lights while meeting reindeer in their natural habitat.",
      "includes": [
        "Professional guide",
        "Warm clothing",
        "Hot drinks",
        "Transportation"
      ],
      "requirements": [
        "Minimum age 8 years",
        "Warm clothing recommended"
      ],
      "rating": 4.8,
      "review_count": 324,
      "images": [
        "https://cdn.nordicexplorer.com/adventures/001/hero.jpg",
        "https://cdn.nordicexplorer.com/adventures/001/gallery1.jpg"
      ],
      "available_dates": [
        "2025-02-15",
        "2025-02-16",
        "2025-02-17"
      ],
      "booking_url": "https://nordicexplorer.com/book/adventure_001"
    }
  ],
  "pagination": {
    "total": 89,
    "limit": 10,
    "offset": 0,
    "has_more": true
  },
  "filters_applied": {
    "category": "wildlife",
    "difficulty": "easy"
  }
}

Get Adventure Details

Retrieve detailed information about a specific adventure.

GET /adventures/{adventure_id}

Example Request

curl "https://api.nordicexplorer.com/v1/adventures/adventure_001" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "data": {
    "id": "adventure_001",
    "name": "Northern Lights & Reindeer Safari",
    "category": "wildlife",
    "difficulty": "easy",
    "duration": 4,
    "price": 145,
    "currency": "EUR",
    "detailed_description": "Embark on an unforgettable journey through the Arctic wilderness...",
    "itinerary": [
      {
        "time": "18:00",
        "activity": "Hotel pickup and introduction"
      },
      {
        "time": "18:30",
        "activity": "Drive to reindeer farm"
      },
      {
        "time": "19:00",
        "activity": "Meet the reindeer and learn about Sami culture"
      },
      {
        "time": "20:30",
        "activity": "Northern Lights hunting with hot drinks"
      },
      {
        "time": "22:00",
        "activity": "Return to hotels"
      }
    ],
    "equipment_provided": [
      "Arctic overalls",
      "Winter boots",
      "Warm gloves",
      "Traditional Lappish hat"
    ],
    "safety_information": {
      "risk_level": "low",
      "safety_briefing": "Comprehensive safety briefing provided",
      "emergency_procedures": "Guide carries emergency communication device",
      "insurance": "Included in booking price"
    },
    "cancellation_policy": {
      "free_cancellation_hours": 24,
      "partial_refund_hours": 12,
      "weather_policy": "Full refund for weather cancellations"
    },
    "seasonal_availability": {
      "best_months": ["December", "January", "February", "March"],
      "available_months": ["October", "November", "December", "January", "February", "March", "April"]
    }
  }
}

📅 Availability API

Check Availability

Check real-time availability for specific adventures and dates.

GET /adventures/{adventure_id}/availability

Query Parameters

Parameter	Type	Required	Description
`start_date`	string	Yes	Start date (YYYY-MM-DD)
`end_date`	string	No	End date for range check
`participants`	integer	No	Number of participants (default: 1)

Example Request

curl "https://api.nordicexplorer.com/v1/adventures/adventure_001/availability?start_date=2025-02-15&participants=2" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "data": {
    "adventure_id": "adventure_001",
    "requested_date": "2025-02-15",
    "participants": 2,
    "availability": {
      "available": true,
      "spots_remaining": 8,
      "total_capacity": 12,
      "price_per_person": 145,
      "total_price": 290,
      "currency": "EUR"
    },
    "time_slots": [
      {
        "start_time": "18:00",
        "end_time": "22:00",
        "available": true,
        "spots_remaining": 8
      }
    ],
    "alternative_dates": [
      {
        "date": "2025-02-16",
        "available": true,
        "spots_remaining": 12
      },
      {
        "date": "2025-02-17", 
        "available": true,
        "spots_remaining": 6
      }
    ]
  }
}

🛒 Booking API

Create Booking

Create a new booking for an adventure.

POST /bookings

Request Body

{
  "adventure_id": "adventure_001",
  "booking_date": "2025-02-15",
  "participants": [
    {
      "type": "adult",
      "first_name": "John",
      "last_name": "Smith",
      "email": "[email protected]",
      "phone": "+358401234567",
      "age": 35,
      "dietary_requirements": ["vegetarian"],
      "medical_conditions": []
    },
    {
      "type": "adult", 
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "[email protected]",
      "phone": "+358401234568",
      "age": 32,
      "dietary_requirements": [],
      "medical_conditions": ["diabetes"]
    }
  ],
  "contact_info": {
    "primary_email": "[email protected]",
    "primary_phone": "+358401234567",
    "emergency_contact": {
      "name": "Robert Smith",
      "phone": "+1234567890",
      "relationship": "brother"
    }
  },
  "special_requests": "Celebrating anniversary",
  "payment_method": "credit_card",
  "marketing_consent": true
}

Example Response

{
  "data": {
    "booking_id": "booking_12345",
    "status": "confirmed",
    "adventure_id": "adventure_001",
    "booking_date": "2025-02-15",
    "participant_count": 2,
    "total_price": 290,
    "currency": "EUR",
    "payment_status": "paid",
    "confirmation_code": "NE-ABC123",
    "booking_details": {
      "meeting_point": "Hotel Kämp, Helsinki",
      "pickup_time": "18:00",
      "guide_contact": "+358501234567",
      "what_to_bring": [
        "Warm clothing",
        "Camera",
        "Identification"
      ]
    },
    "cancellation_deadline": "2025-02-14T18:00:00Z",
    "created_at": "2025-01-15T10:30:00Z"
  }
}

Get Booking Details

Retrieve details for a specific booking.

GET /bookings/{booking_id}

Example Response

{
  "data": {
    "booking_id": "booking_12345",
    "status": "confirmed",
    "adventure": {
      "id": "adventure_001",
      "name": "Northern Lights & Reindeer Safari",
      "date": "2025-02-15",
      "time": "18:00-22:00"
    },
    "participants": [
      {
        "first_name": "John",
        "last_name": "Smith",
        "type": "adult"
      },
      {
        "first_name": "Jane", 
        "last_name": "Smith",
        "type": "adult"
      }
    ],
    "total_price": 290,
    "payment_status": "paid",
    "confirmation_code": "NE-ABC123"
  }
}

Modify Booking

Update an existing booking (subject to availability and policies).

PUT /bookings/{booking_id}

Cancel Booking

Cancel an existing booking.

DELETE /bookings/{booking_id}

Example Response

{
  "data": {
    "booking_id": "booking_12345",
    "status": "cancelled",
    "cancellation_reason": "customer_request",
    "refund_amount": 290,
    "refund_method": "original_payment_method",
    "refund_processing_time": "3-5 business days",
    "cancelled_at": "2025-01-20T14:30:00Z"
  }
}

🏨 Accommodations API

Get Accommodations

Retrieve available accommodations with filtering.

GET /accommodations

Query Parameters

Parameter	Type	Description
`type`	string	Filter by accommodation type
`location`	string	Filter by location
`check_in`	string	Check-in date (YYYY-MM-DD)
`check_out`	string	Check-out date (YYYY-MM-DD)
`guests`	integer	Number of guests
`price_min`	integer	Minimum price per night
`price_max`	integer	Maximum price per night

Example Response

{
  "data": [
    {
      "id": "accommodation_001",
      "name": "Arctic TreeHouse Hotel",
      "type": "unique_hotel",
      "location": {
        "country": "Finland",
        "city": "Rovaniemi"
      },
      "price_per_night": 320,
      "currency": "EUR",
      "rating": 4.9,
      "amenities": [
        "Northern Lights viewing",
        "Private bathroom",
        "Heated floors",
        "Restaurant on-site"
      ],
      "unique_features": [
        "Glass ceiling for aurora viewing",
        "Treehouse design",
        "Eco-friendly construction"
      ],
      "images": [
        "https://cdn.nordicexplorer.com/accommodations/001/hero.jpg"
      ],
      "availability": {
        "available": true,
        "rooms_remaining": 3
      }
    }
  ]
}

🌤️ Weather API

Get Weather Information

Retrieve current and forecast weather for adventure locations.

GET /weather/{location}

Example Response

{
  "data": {
    "location": {
      "name": "Rovaniemi, Finland",
      "coordinates": {
        "latitude": 66.5039,
        "longitude": 25.7294
      }
    },
    "current": {
      "temperature": -15,
      "feels_like": -22,
      "conditions": "clear",
      "visibility": "excellent",
      "wind_speed": 12,
      "wind_direction": "NW",
      "humidity": 68,
      "pressure": 1013
    },
    "aurora_forecast": {
      "tonight": {
        "probability": 75,
        "activity_level": "moderate",
        "best_viewing_time": "22:00-02:00",
        "cloud_cover": 20
      }
    },
    "5_day_forecast": [
      {
        "date": "2025-02-16",
        "high": -12,
        "low": -20,
        "conditions": "partly_cloudy",
        "precipitation": 0,
        "aurora_probability": 60
      }
    ]
  }
}

📊 Analytics API

Get Booking Statistics

Retrieve booking and performance analytics (Partner/Enterprise only).

GET /analytics/bookings

Query Parameters

Parameter	Type	Description
`start_date`	string	Start date for analytics
`end_date`	string	End date for analytics
`groupby`	string	Group by (day/week/month)
`adventure_id`	string	Filter by specific adventure

Example Response

{
  "data": {
    "period": {
      "start_date": "2025-01-01",
      "end_date": "2025-01-31"
    },
    "summary": {
      "total_bookings": 1247,
      "total_revenue": 184350,
      "average_booking_value": 148,
      "cancellation_rate": 0.08,
      "customer_satisfaction": 4.8
    },
    "top_adventures": [
      {
        "adventure_id": "adventure_001",
        "name": "Northern Lights & Reindeer Safari",
        "bookings": 324,
        "revenue": 47080,
        "satisfaction": 4.9
      }
    ],
    "bookings_by_day": [
      {
        "date": "2025-01-01",
        "bookings": 42,
        "revenue": 6210
      }
    ]
  }
}

🔐 Authentication

API Key Authentication

Include your API key in the Authorization header:

curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://api.nordicexplorer.com/v1/adventures

OAuth 2.0 (Partner Integration)

For partner integrations, use OAuth 2.0 flow:

Step 1: Authorization Request

GET https://auth.nordicexplorer.com/oauth/authorize?
    client_id=YOUR_CLIENT_ID&
    response_type=code&
    scope=bookings:read+bookings:write&
    redirect_uri=YOUR_REDIRECT_URI

Step 2: Token Exchange

curl -X POST https://auth.nordicexplorer.com/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code&
      code=AUTHORIZATION_CODE&
      client_id=YOUR_CLIENT_ID&
      client_secret=YOUR_CLIENT_SECRET&
      redirect_uri=YOUR_REDIRECT_URI"

⚠️ Error Handling

HTTP Status Codes

200 - Success
201 - Created
400 - Bad Request
401 - Unauthorized
403 - Forbidden
404 - Not Found
429 - Rate Limit Exceeded
500 - Internal Server Error

Error Response Format

{
  "error": {
    "code": "ADVENTURE_NOT_FOUND",
    "message": "The specified adventure could not be found",
    "details": {
      "adventure_id": "invalid_adventure_123"
    },
    "timestamp": "2025-01-20T15:30:00Z",
    "request_id": "req_abc123def456"
  }
}

Common Error Codes

Code	Description
`INVALID_API_KEY`	API key is missing or invalid
`RATE_LIMIT_EXCEEDED`	Too many requests
`ADVENTURE_NOT_FOUND`	Adventure ID does not exist
`NO_AVAILABILITY`	No spots available for requested date
`INVALID_DATE`	Date format is incorrect
`BOOKING_NOT_FOUND`	Booking ID does not exist
`PAYMENT_FAILED`	Payment processing failed

📚 SDKs and Libraries

Official SDKs

JavaScript/Node.js: npm install nordic-explorer-api
Python: pip install nordic-explorer-sdk
PHP: composer require nordic-explorer/api-client
Ruby: gem install nordic_explorer_api

Example Usage (JavaScript)

const NordicExplorer = require('nordic-explorer-api');

const client = new NordicExplorer('YOUR_API_KEY');

// Get adventures
const adventures = await client.adventures.list({
  category: 'winter-sports',
  difficulty: 'moderate'
});

// Create booking
const booking = await client.bookings.create({
  adventure_id: 'adventure_001',
  booking_date: '2025-02-15',
  participants: [
    {
      type: 'adult',
      first_name: 'John',
      last_name: 'Smith',
      email: '[email protected]'
    }
  ]
});

🧪 Testing

Sandbox Environment

Test your integration using our sandbox environment:

Sandbox URL: https://sandbox-api.nordicexplorer.com/v1
Test API Key: sk_test_12345abcdef

Test Data

Test adventures with predictable IDs
Mock payment processing
Simulated availability responses
No actual bookings created

🔌 API Documentation Last updated: January 2025 API Version: v1.2.0

📚 Related Pages: