# Getting Started with Epic Charging API

Welcome to the Epic Charging API! This guide will help you get up and running quickly with our comprehensive charging infrastructure management API.

## Overview

The Epic Charging API provides a powerful way to monitor, control, and analyze your electric vehicle charging infrastructure. Whether you're managing a single location or a nationwide network, our API gives you the tools to optimize your charging operations.

## Prerequisites

Before you begin, you'll need:

- An Epic Charging account with API access
- Your API key (available in your account dashboard)
- Basic knowledge of REST APIs and JSON
- A tool for making HTTP requests (like cURL, Postman, or your preferred programming language)


## Step 1: Authentication

All requests to the Epic Charging API require authentication using your API key. Include your key in the `Token-Authorization` header:


```bash
curl -X GET \
  https://{{tenant}}.epiccharging.com/api/external/v1/charger/ \
  -H "Token-Authorization: your_api_key_here"
```

## Step 2: Exploring Your Chargers

Let's start by retrieving a list of chargers in your network:


```bash
curl -X GET \
  https://{{tenant}}.epiccharging.com/api/external/v1/charger/ \
  -H "Token-Authorization: your_api_key_here"
```

This will return a JSON response with information about all chargers in your network:


```json
{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "custom_id": "MAIN-01",
      "charger_point_id": "CP001",
      "status": {
        "key": "AVAILABLE",
        "value": "Available"
      },
      "location_name": "Headquarters",
      "temperature": 25.5,
      "payment_type": "Paid",
      "id_tag_required": true,
      "customer_qr_code": "https://qr.epiccharging.com/c/CP001",
      "ports": [...]
    },
    {
      "id": "223e4567-e89b-12d3-a456-426614174001",
      "custom_id": "BRANCH-02",
      "charger_point_id": "CP002",
      "status": {
        "key": "CHARGING",
        "value": "Charging"
      },
      "location_name": "Branch Office",
      "temperature": 24.0,
      "payment_type": "Free",
      "id_tag_required": false,
      "customer_qr_code": "https://qr.epiccharging.com/c/CP002",
      "ports": [...]
    }
  ]
}
```

## Step 3: Managing Charging Sessions

You can start a charging session on a specific port using the following endpoint:


```bash
curl -X PATCH \
  https://{{tenant}}.epiccharging.com/api/external/v1/charger-port/123e4567-e89b-12d3-a456-426614174000/start/ \
  -H "Token-Authorization: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'
```

And stop it when charging is complete:


```bash
curl -X PATCH \
  https://{{tenant}}.epiccharging.com/api/external/v1/charger-port/123e4567-e89b-12d3-a456-426614174000/stop/ \
  -H "Token-Authorization: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'
```

## Step 4: Reserving Chargers

To reserve a charger for future use:


```bash
curl -X PATCH \
  https://{{tenant}}.epiccharging.com/api/external/v1/charger-port/123e4567-e89b-12d3-a456-426614174000/reserve_now/ \
  -H "Token-Authorization: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "expiry_date_time": "2025-03-15T15:00:00Z",
    "id_tag": "USER12345",
    "reservation_id": 98765
  }'
```

## Step 5: Generating Reports

Get detailed charging session reports for analysis:


```bash
curl -X GET \
  "https://{{tenant}}.epiccharging.com/api/external/v1/report/charging-session/?plug_in_start_datetime__gte=2025-03-01T00:00:00Z&plug_in_start_datetime__lte=2025-03-10T23:59:59Z" \
  -H "Token-Authorization: your_api_key_here"
```

## Next Steps

Now that you've mastered the basics, you can explore more advanced features in our documentation:

- Check out the complete [API Reference](/apis)
- Explore [Use Cases and Examples](/use_cases)
- Learn about [Reporting Capabilities](/reporting)
- Review our [Legal Terms](/legal/terms)


## Sample Applications

Here's a simple Node.js application that monitors charger status:


```javascript
const axios = require('axios');

const API_KEY = 'your_api_key_here';
const BASE_URL = 'https://{{tenant}}.epiccharging.com/api/external/v1';

async function monitorChargers() {
  try {
    const response = await axios.get(`${BASE_URL}/charger/`, {
      headers: {
        'Token-Authorization': API_KEY
      }
    });
    
    console.log(`Monitoring ${response.data.count} chargers:`);
    
    response.data.results.forEach(charger => {
      console.log(`- ${charger.custom_id} (${charger.location_name}): ${charger.status.value}`);
      
      // Log details about each port
      charger.ports.forEach(port => {
        console.log(`  - Port ${port.connector_id}: ${port.status.value}, ${port.charge_current_kilowatt_hour} kW`);
      });
    });
  } catch (error) {
    console.error('Error monitoring chargers:', error.message);
  }
}

// Run the monitoring function every 5 minutes
setInterval(monitorChargers, 5 * 60 * 1000);
monitorChargers(); // Run immediately on startup
```

## Need Help?

If you encounter any issues or have questions about using the API, please refer to our documentation or contact our support team for assistance.

Happy charging!