# Carrier Metadata

The Carrier Metadata endpoint returns information about all the carriers available on the EasyPost platform.
This information may include service levels, predefined packages, shipment options, supported features, and more that are available per carrier.
This metadata can be useful during onboarding and integration or when determining the ideal carrier mix for your setup.

---

## CarrierMetadata object

| Property | Type | Description |
|----------|------|-------------|
| carrier | string | The single-word name of a carrier, such as "royalmail" |
| human_readable | string | The human-readable name of the carrier |
| service_levels | array | A list of service level objects for this carrier |
| predefined_packages | array | A list of predefined package objects for this carrier |
| supported_features | array | A list of supported feature objects for this carrier |
| shipment_options | array | A list of shipment option objects for this carrier |

Example Object:

```json
{
  "carriers": [
    {
      "human_readable": "USPS",
      "name": "usps",
      "predefined_packages": [
        {
          "carrier": "usps",
          "description": null,
          "dimensions": ["6in x 4.5in x 0.016in"],
          "human_readable": null,
          "max_weight": null,
          "name": "Card"
        },
        {
          "carrier": "usps",
          "description": null,
          "dimensions": ["11.5in x 6.125in x 0.25in"],
          "human_readable": null,
          "max_weight": null,
          "name": "Letter"
        },
        {
          "carrier": "usps",
          "description": null,
          "dimensions": ["11.5in x 6.125in x 0.75in"],
          "human_readable": null,
          "max_weight": null,
          "name": "Flat"
        },
        {
          "carrier": "usps",
          "description": null,
          "dimensions": ["12.5in x 9.5in"],
          "human_readable": null,
          "max_weight": null,
          "name": "FlatRateEnvelope"
        },
        {
          "carrier": "usps",
          "description": null,
          "dimensions": ["15in x 9.5in"],
          "human_readable": null,
          "max_weight": null,
          "name": "FlatRateLegalEnvelope"
        },
        {
          "carrier": "usps",
          "description": null,
          "dimensions": ["12.5in x 9.5in"],
          "human_readable": null,
          "max_weight": null,
          "name": "FlatRatePaddedEnvelope"
        },
        {
          "carrier": "usps",
          "description": null,
          "dimensions": ["10in x 5in", "12.5in x 9.5in"],
          "human_readable": null,
          "max_weight": null,
          "name": "FlatRateWindowEnvelope"
        },
        {
          "carrier": "usps",
          "description": null,
          "dimensions": ["12.5in x 9.5in"],
          "human_readable": null,
          "max_weight": null,
          "name": "FlatRateCardboardEnvelope"
        },
        {
          "carrier": "usps",
          "description": null,
          "dimensions": ["10in x 6in"],
          "human_readable": null,
          "max_weight": null,
          "name": "SmallFlatRateEnvelope"
        },
        {
          "carrier": "usps",
          "description": null,
          "dimensions": ["Varies based on service level"],
          "human_readable": null,
          "max_weight": null,
          "name": "Parcel"
        },
        {
          "carrier": "usps",
          "description": null,
          "dimensions": ["Varies based on service level"],
          "human_readable": null,
          "max_weight": 320.0,
          "name": "SoftPack"
        },
        {
          "carrier": "usps",
          "description": null,
          "dimensions": ["8.6875in x 5.4375in x 1.75in"],
          "human_readable": null,
          "max_weight": null,
          "name": "SmallFlatRateBox"
        },
        {
          "carrier": "usps",
          "description": null,
          "dimensions": ["11.25in x 8.75in x 6in", "14.125in x 12in x 3.5in"],
          "human_readable": null,
          "max_weight": null,
          "name": "MediumFlatRateBox"
        },
        {
          "carrier": "usps",
          "description": null,
          "dimensions": ["12.25in x 12in x 6in"],
          "human_readable": null,
          "max_weight": null,
          "name": "LargeFlatRateBox"
        },
        {
          "carrier": "usps",
          "description": null,
          "dimensions": ["12.25in x 12.25in x 6in"],
          "human_readable": null,
          "max_weight": null,
          "name": "LargeFlatRateBoxAPOFPO"
        },
        {
          "carrier": "usps",
          "description": null,
          "dimensions": [],
          "human_readable": null,
          "max_weight": null,
          "name": "FlatTubTrayBox"
        },
        {
          "carrier": "usps",
          "description": null,
          "dimensions": [],
          "human_readable": null,
          "max_weight": null,
          "name": "EMMTrayBox"
        },
        {
          "carrier": "usps",
          "description": null,
          "dimensions": [],
          "human_readable": null,
          "max_weight": null,
          "name": "FullTrayBox"
        },
        {
          "carrier": "usps",
          "description": null,
          "dimensions": [],
          "human_readable": null,
          "max_weight": null,
          "name": "HalfTrayBox"
        },
        {
          "carrier": "usps",
          "description": null,
          "dimensions": [],
          "human_readable": null,
          "max_weight": null,
          "name": "PMODSack"
        }
      ],
      "service_levels": [
        {
          "carrier": "usps",
          "description": "1-5 business days",
          "dimensions": [
            "Cards, Letters and Flats only (no Parcels)",
            "See Predefined Packages (Card, Letter, Flat) for details"
          ],
          "human_readable": "First-Class Mail\u00ae",
          "max_weight": 13.0,
          "name": "First"
        },
        {
          "carrier": "usps",
          "description": "1-3 business days",
          "dimensions": ["Combined Length and Girth < 108in"],
          "human_readable": "Priority Mail\u00ae",
          "max_weight": 1120.0,
          "name": "Priority"
        },
        {
          "carrier": "usps",
          "description": "1-2 days",
          "dimensions": ["Combined Length and Girth < 108in"],
          "human_readable": "Priority Mail Express\u00ae",
          "max_weight": 1120.0,
          "name": "Express"
        },
        {
          "carrier": "usps",
          "description": "2-5 days",
          "dimensions": ["Combined Length and Girth < 130in"],
          "human_readable": "USPS Ground Advantage\u00ae",
          "max_weight": 70.0,
          "name": "GroundAdvantage"
        },
        {
          "carrier": "usps",
          "description": "2-8 business days",
          "dimensions": ["Combined Length and Girth < 108in"],
          "human_readable": "Library Mail\u00ae",
          "max_weight": 1120.0,
          "name": "LibraryMail"
        },
        {
          "carrier": "usps",
          "description": "2-8 business days",
          "dimensions": ["Combined Length and Girth < 108in"],
          "human_readable": "Media Mail\u00ae",
          "max_weight": 1120.0,
          "name": "MediaMail"
        },
        {
          "carrier": "usps",
          "description": null,
          "dimensions": ["Must be rectangular, otherwise an additional charge may apply."],
          "human_readable": "First-Class Mail International\u00ae",
          "max_weight": 15.994,
          "name": "FirstClassMailInternational"
        },
        {
          "carrier": "usps",
          "description": "7-21 days",
          "dimensions": [
            "Packages (Other Than Rolls): Combined Length and Girth < 108in",
            "Rolls (Tubes): Length: min 4in; max 36 in. Length plus twice the diameter (combined): min 6.75 in; max 42in.",
            "Some countries have specific prohibitions and restrictions"
          ],
          "human_readable": "First-Class Package International Service\u00ae",
          "max_weight": 64.0,
          "name": "FirstClassPackageInternationalService"
        },
        {
          "carrier": "usps",
          "description": "6-10 business days",
          "dimensions": ["Combined Length and Girth < 108in"],
          "human_readable": "Priority Mail International\u00ae",
          "max_weight": 1120.0,
          "name": "PriorityMailInternational"
        },
        {
          "carrier": "usps",
          "description": "3-5 business days",
          "dimensions": ["Combined Length and Girth < 108in"],
          "human_readable": "Priority Mail Express International\u00ae",
          "max_weight": 1120.0,
          "name": "ExpressMailInternational"
        }
      ]
    }
  ]
}
```

---

## Retrieve Carrier Metadata

### Example: GET /metadata/carriers

#### cURL

```shell
# Request all metadata for all carriers
curl -X GET https://api.easypost.com/v2/metadata/carriers \
  -u "EASYPOST_API_KEY":

# Request specific metadata for specific carriers
curl -X GET "https://api.easypost.com/v2/metadata/carriers?carriers=usps&types=service_levels,predefined_packages" \
  -u "EASYPOST_API_KEY":
```

#### Go

```go
package example

import (
	"fmt"

	"github.com/EasyPost/easypost-go/v5"
)

func retrieve() {
	client := easypost.New("EASYPOST_API_KEY")

	// Request all metadata for all carriers
	carrierMetadata, _ := client.GetCarrierMetadata()
	fmt.Println(carrierMetadata)

	// Request specific metadata for specific carriers
	carrierMetadataWithFilters, _ := client.GetCarrierMetadataWithCarriersAndTypes([]string{"usps"}, []string{"service_levels", "predefined_packages"})
	fmt.Println(carrierMetadataWithFilters)
}
```

#### Java

```java
package carrier_metadata;

import com.easypost.exception.EasyPostException;
import com.easypost.model.CarrierAccount;
import com.easypost.service.EasyPostClient;

import java.util.ArrayList;
import java.util.List;

public class Retrieve {
    public static void main(String[] args) throws EasyPostException {
        EasyPostClient client = new EasyPostClient("EASYPOST_API_KEY");

        // Request all metadata for all carriers
        CarrierAccount carrierMetadata = client.carrierMetadata.retrieve();
        System.out.println(carrierMetadata);

        // Request specific metadata for specific carriers
        List<String> carriers = new ArrayList<String>();
        carriers.add("usps");

        List<String> types = new ArrayList<String>();
        types.add("service_levels");
        types.add("predefined_packages");

        CarrierAccount carrierMetadata = client.carrierMetadata.retrieve(carriers, types);
        System.out.println(carrierMetadata);
    }
}
```

#### C#

```csharp
using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using EasyPost;
using Newtonsoft.Json;

namespace EasyPostExamples
{
    public class Examples
    {
        public static async Task Main()
        {
            var client = new EasyPost.Client(new EasyPost.ClientConfiguration("EASYPOST_API_KEY"));

            // Request all metadata for all carriers
            List<EasyPost.Models.API.Carrier> carrierMetadata = await client.CarrierMetadata.Retrieve();
            Console.WriteLine(JsonConvert.SerializeObject(carrierMetadata, Formatting.Indented));

            // Request specific metadata for specific carriers
            EasyPost.Parameters.CarrierMetadata.Retrieve parameters = new()
            {
                Carriers = new List<string> { "UPS", "USPS" },
                Types = new List<EasyPost.Models.API.CarrierMetadataType> { CarrierMetadataType.ServiceLevels, CarrierMetadataType.PredefinedPackages },
            };

            List<EasyPost.Models.API.Carrier> carrierMetadata = await client.CarrierMetadata.Retrieve(parameters);
            Console.WriteLine(JsonConvert.SerializeObject(carrierMetadata, Formatting.Indented));
        }
    }
}
```

#### Node.js

```javascript
const EasyPostBetaClient = require('@easypost/api');

const client = new EasyPostBetaClient('EASYPOST_API_KEY');

(async () => {
  // Request all metadata for all carriers
  const carrierMetadata = await client.CarrierMetadata.retrieve();
  console.log(carrierMetadata);

  // Request specific metadata for specific carriers
  const carrierMetadataWithFilters = await client.CarrierMetadata.retrieve(
    ['usps'],
    ['service_levels', 'predefined_packages'],
  );
  console.log(carrierMetadataWithFilters);
})();
```

#### PHP

```php
<?php

$client = new \EasyPost\EasyPostClient('EASYPOST_API_KEY');

// Request all metadata for all carriers
$carrierMetadata = $client->carrierMetadata->retrieve();
echo $carrierMetadata;

// Request specific metadata for specific carriers
$carrierMetadata = $client->carrierMetadata->retrieve(
    ['usps'],
    ['service_levels', 'predefined_packages'],
);
echo $carrierMetadata;
```

#### Python

```python
import easypost

client = easypost.EasyPostClient("EASYPOST_API_KEY")

# Request all metadata for all carriers
carrier_metadata = client.carrier_metadata.retrieve()
print(carrier_metadata)

# Request specific metadata for specific carriers
carrier_metadata = client.carrier_metadata.retrieve(
    carriers=["usps"],
    types=["service_levels", "predefined_packages"],
)
print(carrier_metadata)
```

#### Ruby

```ruby
require 'easypost'

client = EasyPost::Client.new(api_key: 'EASYPOST_API_KEY')

# Request all metadata for all carriers
carrier_metadata = client.carrier_metadata.retrieve
puts carrier_metadata

# Request specific metadata for specific carriers
usps_carrier_metadata = client.carrier_metadata.retrieve('usps', %w[service_levels predefined_packages])
puts usps_carrier_metadata
```

Retrieve all `CarrierMetadata` for all carriers on the EasyPost platform.
Optionally, filter the response by specifying a list of carriers or metadata types.