# Shipping Location Finder (USPS, UPS, FedEx) (`muhammadafzal/shipping-location-finder`) Actor

Find nearby USPS, UPS, and FedEx locations by US ZIP code with normalized addresses, hours, services, coordinates, distance, and official source URLs.

- **URL**: https://apify.com/muhammadafzal/shipping-location-finder.md
- **Developed by:** [Muhammad Afzal](https://apify.com/muhammadafzal) (community)
- **Categories:** E-commerce
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.00 / 1,000 shipping locations

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Shipping Location Finder (USPS, UPS, FedEx)

Find nearby USPS, UPS, and FedEx shipping locations from the carriers’ official US location directories. Enter a five-digit ZIP code and receive normalized records for post offices, carrier stores, authorized shipping outlets, drop-off partners, and other listed service points.

This Actor is designed for logistics apps, returns workflows, customer-support tools, local directory enrichment, and AI agents that need one consistent result shape across the three major US parcel carriers.

### What it extracts

| Field | Description |
| --- | --- |
| `carrier` | `USPS`, `UPS`, or `FedEx` |
| `locationId` | Carrier directory identifier |
| `name`, `locationType` | Public location name and carrier-defined category |
| `streetAddress`, `city`, `state`, `postalCode` | Normalized US address fields |
| `phone` | Public location or carrier phone number, when listed |
| `latitude`, `longitude` | Exact coordinates when exposed by the official directory |
| `distanceMiles` | Distance from the query ZIP centroid |
| `distanceIsApproximate` | `true` when distance is based on ZIP centroids |
| `hours` | Weekly carrier-published hours when available |
| `services` | Drop-off or service information shown on the listing |
| `sourceUrl` | Official carrier page used for the record |
| `queriedZipCode`, `scrapedAt` | Search provenance and collection timestamp |

### When to use it

Use this Actor when you need a bounded, repeatable location lookup by US ZIP code. It is a good fit for showing nearby return points, comparing carrier coverage, routing a customer to a staffed counter, or feeding normalized locations into another Actor or agent.

Do not use it as a routing engine, a guarantee that a location accepts a particular parcel, or a source of real-time holiday closures. Confirm time-sensitive services and opening hours on the linked carrier page before sending a customer to a location.

### Input

| Field | Type | Default | Notes |
| --- | --- | --- | --- |
| `zipCode` | string | `10001` | Required five-digit US ZIP code |
| `carriers` | array | all three | Any combination of `USPS`, `UPS`, and `FedEx` |
| `radiusMiles` | integer | `10` | 1–25 miles |
| `maxResults` | integer | `50` | 1–200 records across all carriers |
| `proxyConfiguration` | object | US residential Apify Proxy | Used only for the Akamai-protected USPS browser path |

Example input:

```json
{
  "zipCode": "10001",
  "carriers": ["USPS", "UPS", "FedEx"],
  "radiusMiles": 10,
  "maxResults": 25,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": ["RESIDENTIAL"],
    "apifyProxyCountry": "US"
  }
}
```

Run through the Apify API:

```bash
curl -X POST "https://api.apify.com/v2/acts/<username>~shipping-location-finder/runs?token=$APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"zipCode":"10001","carriers":["USPS","UPS","FedEx"],"radiusMiles":10,"maxResults":25}'
```

The dataset can then be read through the run’s `defaultDatasetId`, while the `OUTPUT` key-value-store record contains per-carrier diagnostics.

### Output example

```json
{
  "carrier": "FedEx",
  "locationId": "TSSAA",
  "name": "FedEx at Walgreens",
  "locationType": "FedEx at Walgreens",
  "streetAddress": "383 W 31st St",
  "city": "New York",
  "state": "NY",
  "postalCode": "10001",
  "countryCode": "US",
  "phone": "(800) 463-3339",
  "latitude": null,
  "longitude": null,
  "distanceMiles": 0,
  "distanceIsApproximate": true,
  "hours": null,
  "services": [],
  "sourceUrl": "https://local.fedex.com/en-us/ny/new-york/tssaa",
  "queriedZipCode": "10001",
  "scrapedAt": "2026-08-27T06:00:00.000Z"
}
```

### Pricing

The Actor uses transparent pay-per-event pricing. Apify automatically charges both synthetic events; the code does not manually charge them.

| Event | Price | Charged when |
| --- | ---: | --- |
| Actor start | $0.00005 | A run starts (once up to 1 GB memory) |
| Shipping location (`shipping-location`) | $0.002 | One validated record is written to the default dataset |

A run returning 25 locations costs approximately **$0.05005** in event charges. A truthful empty or blocked run has no location-item charges; only the start event applies. The configured maximum run charge and `maxResults` remain the user’s cost controls.

### Reliability and limitations

UPS and FedEx expose server-rendered official directory pages, so the Actor fetches and parses those pages directly. It discovers carrier-owned city pages from the relevant state directory rather than relying on a third-party geocoder.

The official USPS locator is JavaScript-driven and protected by Akamai. The Actor uses one consistent Playwright session and a US residential proxy for that path. If USPS blocks the session, UPS and FedEx results are preserved and `OUTPUT.carrierOutcomes` identifies USPS as blocked. No fabricated USPS records are added and no result events are charged for missing records.

Distance is exact when a carrier exposes coordinates. Otherwise it is an approximation between the query and result ZIP centroids, and `distanceIsApproximate` is set to `true`. Carrier directory coverage, services, and hours can change without notice. The Actor limits nearby city discovery to 20 cities per run to keep runtime and cost bounded.

### Legal and data use

The Actor reads public carrier location pages and returns factual business-location information with a link to the official source. Follow the carriers’ terms, applicable law, and Apify’s policies. Do not use the data for spam, surveillance, or decisions involving sensitive personal information. Carrier names and trademarks belong to their respective owners; this Actor is not endorsed by USPS, UPS, or FedEx.

### Support

If a carrier changes its directory markup, include the run ID, input ZIP code, affected carrier, and the `OUTPUT` diagnostic in your issue. Do not include Apify tokens, proxy URLs, cookies, or other secrets.

# Actor input Schema

## `zipCode` (type: `string`):

Use this when you need carrier locations near a US ZIP code. Enter exactly five digits, for example `10001`. ZIP+4 and non-US postal codes are not supported.

## `carriers` (type: `array`):

Use this to limit the official directories queried. Choose one or more of USPS, UPS, and FedEx; all three are searched by default.

## `radiusMiles` (type: `integer`):

Use this to bound nearby cities and returned locations. Accepted range is 1–25 miles; distances for directory-only records are approximated from ZIP centroids.

## `maxResults` (type: `integer`):

Use this to cap the total records across all selected carriers. Accepted range is 1–200; the nearest matches are returned first.

## `proxyConfiguration` (type: `object`):

Use this for the USPS browser request, which is protected by Akamai. A US residential Apify Proxy session is recommended; UPS and FedEx use static official pages.

## Actor input object example

```json
{
  "zipCode": "10001",
  "carriers": [
    "USPS",
    "UPS",
    "FedEx"
  ],
  "radiusMiles": 10,
  "maxResults": 50,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ],
    "apifyProxyCountry": "US"
  }
}
```

# Actor output Schema

## `results` (type: `string`):

Schema-validated USPS, UPS, and FedEx location records.

## `summary` (type: `string`):

Per-carrier outcomes, warnings, and delivered result counts.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "zipCode": "10001",
    "carriers": [
        "USPS",
        "UPS",
        "FedEx"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("muhammadafzal/shipping-location-finder").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "zipCode": "10001",
    "carriers": [
        "USPS",
        "UPS",
        "FedEx",
    ],
}

# Run the Actor and wait for it to finish
run = client.actor("muhammadafzal/shipping-location-finder").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "zipCode": "10001",
  "carriers": [
    "USPS",
    "UPS",
    "FedEx"
  ]
}' |
apify call muhammadafzal/shipping-location-finder --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,muhammadafzal/shipping-location-finder"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/HjaUSkmQA428kAmTb/builds/mbV6JV5qImW882sP2/openapi.json