Service Map

Retrieve available shipping carriers, vendors, and services. This endpoint provides a comprehensive mapping of all available shipping options and their configurations.

GET /API/v2/service_map.php

Cost: Free (no balance deduction)

Rate Limit: 60 requests per minute

Data: Complete service mapping with carriers, vendors, and services

Service Map Features

  • Complete list of available carriers (USPS, UPS, etc.)
  • Vendor information for each carrier
  • Available services for each vendor
  • Service availability status
  • Service IDs and slugs for API usage

Authentication

This endpoint requires Bearer token authentication. Include your API key in the Authorization header.

curl -X GET https://developers.labelscheap.com/API/v2/service_map.php \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Requested-With: XMLHttpRequest"
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://developers.labelscheap.com/API/v2/service_map.php');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'Authorization: Bearer YOUR_API_KEY',
    'X-Requested-With: XMLHttpRequest'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

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

$data = json_decode($response, true);
import requests

headers = {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY',
    'X-Requested-With': 'XMLHttpRequest'
}

response = requests.get(
    'https://developers.labelscheap.com/API/v2/service_map.php',
    headers=headers
)

data = response.json()
fetch('https://developers.labelscheap.com/API/v2/service_map.php', {
    method: 'GET',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer YOUR_API_KEY',
        'X-Requested-With': 'XMLHttpRequest'
    }
})
.then(response => response.json())
.then(data => console.log(data));

Request

This endpoint accepts a GET request. No request body is required.

Headers

Header Required Description
Content-Type Yes Must be application/json
Authorization Yes Bearer token with your API key
X-Requested-With Yes Must be XMLHttpRequest

Request Body

No request body is required for this endpoint.

Response

The response includes a comprehensive mapping of all available carriers, vendors, and services.

Success Response

{
    "STATUS": "success",
    "MESSAGE": "Service mapping retrieved successfully",
    "CODE": "200",
    "DATA": {
        "carriers": [
            {
                "id": 1,
                "name": "USPS",
                "vendors": [
                    {
                        "id": 5,
                        "name": "Rollo",
                        "slug": "rollo",
                        "is_open": true,
                        "services": [
                            {
                                "id": 1,
                                "name": "Priority",
                                "slug": "priority"
                            },
                            {
                                "id": 3,
                                "name": "Ground Advantage",
                                "slug": "ground_advantage"
                            },
                            {
                                "id": 20,
                                "name": "Priority Mail Express",
                                "slug": "priority_express"
                            }
                        ]
                    },
                    {
                        "id": 6,
                        "name": "Pitney Bowes",
                        "slug": "pitney_bowes",
                        "is_open": true,
                        "services": [
                            {
                                "id": 11,
                                "name": "Priority",
                                "slug": "priority"
                            },
                            {
                                "id": 12,
                                "name": "Ground Advantage",
                                "slug": "ground_advantage"
                            },
                            {
                                "id": 19,
                                "name": "Priority Mail Express",
                                "slug": "priority_express"
                            }
                        ]
                    }
                ]
            },
            {
                "id": 9,
                "name": "USPS Preshipment",
                "vendors": [
                    {
                        "id": 9,
                        "name": "eVS Easypost",
                        "slug": "evs_easypost",
                        "is_open": true,
                        "services": [
                            {
                                "id": 10,
                                "name": "Priority Mail",
                                "slug": "preship"
                            },
                            {
                                "id": 26,
                                "name": "Priority Mail (Back Date)",
                                "slug": "preship_bd"
                            }
                        ]
                    }
                ]
            },
            {
                "id": 10,
                "name": "UPS",
                "vendors": [
                    {
                        "id": 17,
                        "name": "UPS",
                        "slug": "ups",
                        "is_open": true,
                        "services": [
                            {
                                "id": 23,
                                "name": "Standard",
                                "slug": "standard"
                            },
                            {
                                "id": 24,
                                "name": "Ground",
                                "slug": "ground"
                            },
                            {
                                "id": 39,
                                "name": "Next Day Air Early",
                                "slug": "next_day_air_early"
                            }
                        ]
                    }
                ]
            }
        ],
        "total_carriers": 3
    },
    "TIMESTAMP": "2024-01-15 10:30:00"
}

Response Fields

Field Type Description
STATUS string Always "success" for successful requests
MESSAGE string Human-readable success message
CODE string HTTP status code as string
DATA.carriers array Array of available carriers
DATA.carriers[].id integer Unique carrier identifier
DATA.carriers[].name string Carrier name (e.g., "USPS", "UPS")
DATA.carriers[].vendors array Array of vendors for this carrier
DATA.carriers[].vendors[].id integer Unique vendor identifier
DATA.carriers[].vendors[].name string Vendor name (e.g., "Rollo", "Pitney Bowes")
DATA.carriers[].vendors[].slug string Vendor identifier for API usage
DATA.carriers[].vendors[].is_open boolean Whether the vendor is currently available
DATA.carriers[].vendors[].services array Array of available services for this vendor
DATA.carriers[].vendors[].services[].id integer Unique service identifier
DATA.carriers[].vendors[].services[].name string Service name (e.g., "Priority", "Ground")
DATA.carriers[].vendors[].services[].slug string Service identifier for API usage
DATA.total_carriers integer Total number of available carriers
TIMESTAMP string ISO 8601 timestamp of the response

Code Examples

Here are complete examples for different programming languages:

<?php
class LabelsCheapAPI {
    private $apiKey;
    private $baseUrl = 'https://developers.labelscheap.com/API/v2/';
    
    public function __construct($apiKey) {
        $this->apiKey = $apiKey;
    }
    
    public function getServiceMap() {
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, $this->baseUrl . 'service_map.php');
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Content-Type: application/json',
            'Authorization: Bearer ' . $this->apiKey,
            'X-Requested-With: XMLHttpRequest'
        ]);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        
        $response = curl_exec($ch);
        curl_close($ch);
        
        return json_decode($response, true);
    }
    
    public function findService($carrierName, $vendorName, $serviceName) {
        $serviceMap = $this->getServiceMap();
        
        if ($serviceMap['STATUS'] !== 'success') {
            return null;
        }
        
        foreach ($serviceMap['DATA']['carriers'] as $carrier) {
            if (strtolower($carrier['name']) === strtolower($carrierName)) {
                foreach ($carrier['vendors'] as $vendor) {
                    if (strtolower($vendor['name']) === strtolower($vendorName)) {
                        foreach ($vendor['services'] as $service) {
                            if (strtolower($service['name']) === strtolower($serviceName)) {
                                return [
                                    'carrier_id' => $carrier['id'],
                                    'vendor_id' => $vendor['id'],
                                    'service_id' => $service['id'],
                                    'carrier_slug' => strtolower($carrier['name']),
                                    'vendor_slug' => $vendor['slug'],
                                    'service_slug' => $service['slug']
                                ];
                            }
                        }
                    }
                }
            }
        }
        
        return null;
    }
}

// Usage
try {
    $api = new LabelsCheapAPI('YOUR_API_KEY');
    $serviceMap = $api->getServiceMap();
    
    if ($serviceMap['STATUS'] === 'success') {
        echo "Total Carriers: " . $serviceMap['DATA']['total_carriers'] . "\n";
        
        foreach ($serviceMap['DATA']['carriers'] as $carrier) {
            echo "\nCarrier: " . $carrier['name'] . "\n";
            foreach ($carrier['vendors'] as $vendor) {
                echo "  Vendor: " . $vendor['name'] . " (" . ($vendor['is_open'] ? 'Open' : 'Closed') . ")\n";
                foreach ($vendor['services'] as $service) {
                    echo "    Service: " . $service['name'] . " (ID: " . $service['id'] . ")\n";
                }
            }
        }
        
        // Find specific service
        $service = $api->findService('USPS', 'Rollo', 'Priority');
        if ($service) {
            echo "\nFound Service:\n";
            echo "Carrier ID: " . $service['carrier_id'] . "\n";
            echo "Vendor ID: " . $service['vendor_id'] . "\n";
            echo "Service ID: " . $service['service_id'] . "\n";
        }
    } else {
        echo "Error: " . $serviceMap['MESSAGE'] . "\n";
    }
} catch (Exception $e) {
    echo "Error: " . $e->getMessage() . "\n";
}
?>
import requests
import json

class LabelsCheapAPI:
    def __init__(self, api_key):
        self.api_key = api_key
        self.base_url = 'https://developers.labelscheap.com/API/v2/'
        self.headers = {
            'Content-Type': 'application/json',
            'Authorization': f'Bearer {api_key}',
            'X-Requested-With': 'XMLHttpRequest'
        }
    
    def get_service_map(self):
        try:
            response = requests.get(
                f'{self.base_url}service_map.php',
                headers=self.headers,
                timeout=30
            )
            
            response.raise_for_status()
            return response.json()
            
        except requests.exceptions.RequestException as e:
            raise Exception(f'Request failed: {str(e)}')
        except json.JSONDecodeError as e:
            raise Exception(f'Invalid JSON response: {str(e)}')
    
    def find_service(self, carrier_name, vendor_name, service_name):
        service_map = self.get_service_map()
        
        if service_map['STATUS'] != 'success':
            return None
        
        for carrier in service_map['DATA']['carriers']:
            if carrier['name'].lower() == carrier_name.lower():
                for vendor in carrier['vendors']:
                    if vendor['name'].lower() == vendor_name.lower():
                        for service in vendor['services']:
                            if service['name'].lower() == service_name.lower():
                                return {
                                    'carrier_id': carrier['id'],
                                    'vendor_id': vendor['id'],
                                    'service_id': service['id'],
                                    'carrier_slug': carrier['name'].lower(),
                                    'vendor_slug': vendor['slug'],
                                    'service_slug': service['slug']
                                }
        return None

# Usage
try:
    api = LabelsCheapAPI('YOUR_API_KEY')
    service_map = api.get_service_map()
    
    if service_map['STATUS'] == 'success':
        print(f"Total Carriers: {service_map['DATA']['total_carriers']}")
        
        for carrier in service_map['DATA']['carriers']:
            print(f"\nCarrier: {carrier['name']}")
            for vendor in carrier['vendors']:
                status = "Open" if vendor['is_open'] else "Closed"
                print(f"  Vendor: {vendor['name']} ({status})")
                for service in vendor['services']:
                    print(f"    Service: {service['name']} (ID: {service['id']})")
        
        # Find specific service
        service = api.find_service('USPS', 'Rollo', 'Priority')
        if service:
            print(f"\nFound Service:")
            print(f"Carrier ID: {service['carrier_id']}")
            print(f"Vendor ID: {service['vendor_id']}")
            print(f"Service ID: {service['service_id']}")
    else:
        print(f"Error: {service_map['MESSAGE']}")
        
except Exception as e:
    print(f"Error: {str(e)}")
using System;
using System.Net.Http;
using System.Threading.Tasks;
using System.Collections.Generic;
using Newtonsoft.Json;

public class ServiceInfo
{
    public int CarrierId { get; set; }
    public int VendorId { get; set; }
    public int ServiceId { get; set; }
    public string CarrierSlug { get; set; }
    public string VendorSlug { get; set; }
    public string ServiceSlug { get; set; }
}

public class LabelsCheapAPI
{
    private readonly string _apiKey;
    private readonly string _baseUrl = "https://developers.labelscheap.com/API/v2/";
    private readonly HttpClient _httpClient;

    public LabelsCheapAPI(string apiKey)
    {
        _apiKey = apiKey;
        _httpClient = new HttpClient();
        _httpClient.DefaultRequestHeaders.Add("Authorization", $"Bearer {apiKey}");
        _httpClient.DefaultRequestHeaders.Add("X-Requested-With", "XMLHttpRequest");
    }

    public async Task<dynamic> GetServiceMapAsync()
    {
        try
        {
            var response = await _httpClient.GetAsync($"{_baseUrl}service_map.php");
            response.EnsureSuccessStatusCode();
            
            var responseContent = await response.Content.ReadAsStringAsync();
            return JsonConvert.DeserializeObject(responseContent);
        }
        catch (HttpRequestException ex)
        {
            throw new Exception($"Request failed: {ex.Message}");
        }
        catch (JsonException ex)
        {
            throw new Exception($"Invalid JSON response: {ex.Message}");
        }
    }

    public async Task<ServiceInfo> FindServiceAsync(string carrierName, string vendorName, string serviceName)
    {
        var serviceMap = await GetServiceMapAsync();
        
        if (serviceMap.STATUS != "success")
            return null;
        
        foreach (var carrier in serviceMap.DATA.carriers)
        {
            if (carrier.name.ToString().ToLower() == carrierName.ToLower())
            {
                foreach (var vendor in carrier.vendors)
                {
                    if (vendor.name.ToString().ToLower() == vendorName.ToLower())
                    {
                        foreach (var service in vendor.services)
                        {
                            if (service.name.ToString().ToLower() == serviceName.ToLower())
                            {
                                return new ServiceInfo
                                {
                                    CarrierId = (int)carrier.id,
                                    VendorId = (int)vendor.id,
                                    ServiceId = (int)service.id,
                                    CarrierSlug = carrier.name.ToString().ToLower(),
                                    VendorSlug = vendor.slug.ToString(),
                                    ServiceSlug = service.slug.ToString()
                                };
                            }
                        }
                    }
                }
            }
        }
        
        return null;
    }
}

// Usage
public class Program
{
    public static async Task Main()
    {
        try
        {
            var api = new LabelsCheapAPI("YOUR_API_KEY");
            var serviceMap = await api.GetServiceMapAsync();
            
            if (serviceMap.STATUS == "success")
            {
                Console.WriteLine($"Total Carriers: {serviceMap.DATA.total_carriers}");
                
                foreach (var carrier in serviceMap.DATA.carriers)
                {
                    Console.WriteLine($"\nCarrier: {carrier.name}");
                    foreach (var vendor in carrier.vendors)
                    {
                        var status = vendor.is_open ? "Open" : "Closed";
                        Console.WriteLine($"  Vendor: {vendor.name} ({status})");
                        foreach (var service in vendor.services)
                        {
                            Console.WriteLine($"    Service: {service.name} (ID: {service.id})");
                        }
                    }
                }
                
                // Find specific service
                var service = await api.FindServiceAsync("USPS", "Rollo", "Priority");
                if (service != null)
                {
                    Console.WriteLine($"\nFound Service:");
                    Console.WriteLine($"Carrier ID: {service.CarrierId}");
                    Console.WriteLine($"Vendor ID: {service.VendorId}");
                    Console.WriteLine($"Service ID: {service.ServiceId}");
                }
            }
            else
            {
                Console.WriteLine($"Error: {serviceMap.MESSAGE}");
            }
        }
        catch (Exception ex)
        {
            Console.WriteLine($"Error: {ex.Message}");
        }
    }
}
class LabelsCheapAPI {
    constructor(apiKey) {
        this.apiKey = apiKey;
        this.baseUrl = 'https://developers.labelscheap.com/API/v2/';
        this.headers = {
            'Content-Type': 'application/json',
            'Authorization': `Bearer ${apiKey}`,
            'X-Requested-With': 'XMLHttpRequest'
        };
    }

    async getServiceMap() {
        try {
            const response = await fetch(`${this.baseUrl}service_map.php`, {
                method: 'GET',
                headers: this.headers
            });

            if (!response.ok) {
                throw new Error(`HTTP error! status: ${response.status}`);
            }

            return await response.json();
        } catch (error) {
            throw new Error(`Request failed: ${error.message}`);
        }
    }

    async findService(carrierName, vendorName, serviceName) {
        const serviceMap = await this.getServiceMap();
        
        if (serviceMap.STATUS !== 'success') {
            return null;
        }
        
        for (const carrier of serviceMap.DATA.carriers) {
            if (carrier.name.toLowerCase() === carrierName.toLowerCase()) {
                for (const vendor of carrier.vendors) {
                    if (vendor.name.toLowerCase() === vendorName.toLowerCase()) {
                        for (const service of vendor.services) {
                            if (service.name.toLowerCase() === serviceName.toLowerCase()) {
                                return {
                                    carrierId: carrier.id,
                                    vendorId: vendor.id,
                                    serviceId: service.id,
                                    carrierSlug: carrier.name.toLowerCase(),
                                    vendorSlug: vendor.slug,
                                    serviceSlug: service.slug
                                };
                            }
                        }
                    }
                }
            }
        }
        
        return null;
    }
}

// Usage
async function main() {
    try {
        const api = new LabelsCheapAPI('YOUR_API_KEY');
        const serviceMap = await api.getServiceMap();
        
        if (serviceMap.STATUS === 'success') {
            console.log(`Total Carriers: ${serviceMap.DATA.total_carriers}`);
            
            for (const carrier of serviceMap.DATA.carriers) {
                console.log(`\nCarrier: ${carrier.name}`);
                for (const vendor of carrier.vendors) {
                    const status = vendor.is_open ? 'Open' : 'Closed';
                    console.log(`  Vendor: ${vendor.name} (${status})`);
                    for (const service of vendor.services) {
                        console.log(`    Service: ${service.name} (ID: ${service.id})`);
                    }
                }
            }
            
            // Find specific service
            const service = await api.findService('USPS', 'Rollo', 'Priority');
            if (service) {
                console.log('\nFound Service:');
                console.log(`Carrier ID: ${service.carrierId}`);
                console.log(`Vendor ID: ${service.vendorId}`);
                console.log(`Service ID: ${service.serviceId}`);
            }
        } else {
            console.log(`Error: ${serviceMap.MESSAGE}`);
        }
    } catch (error) {
        console.error(`Error: ${error.message}`);
    }
}

main();

Request Tester

Test the service map endpoint with your API key:

Common Error Responses

Here are the most common error responses you might encounter:

Authentication Error (401)

{
    "STATUS": "error",
    "MESSAGE": "Authentication failed: Invalid or missing API key.",
    "CODE": "1002",
    "HTTP_STATUS": 401,
    "DATA": {},
    "TIMESTAMP": "2024-01-15 10:30:00"
}

Rate Limit Exceeded (429)

{
    "STATUS": "error",
    "MESSAGE": "Rate limit exceeded. Please try again later.",
    "CODE": "1010",
    "HTTP_STATUS": 429,
    "DATA": {},
    "TIMESTAMP": "2024-01-15 10:30:00"
}

Service Unavailable (503)

{
    "STATUS": "error",
    "MESSAGE": "Service is currently unavailable",
    "CODE": "3004",
    "HTTP_STATUS": 503,
    "DATA": {},
    "TIMESTAMP": "2024-01-15 10:30:00"
}

Error Handling Best Practices

  • Cache service map data to reduce API calls
  • Handle rate limiting by implementing exponential backoff
  • Implement retry logic for transient errors (5xx status codes)
  • Check vendor availability before using services
  • Display user-friendly error messages based on the error code
  • Log error details for debugging and monitoring