Service Map
Retrieve available shipping carriers, vendors, and services. This endpoint provides a comprehensive mapping of all available shipping options and their configurations.
/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