Skip to main content

Postman

Use this guide to import the PortPulse OpenAPI, configure an API Key header, and send your first request.

What you’ll need​

  • Base URL: https://api.useportpulse.com
  • Demo key: dev_demo_123
  • Auth header: X-API-Key: <dev_demo_123>
  • Formats: JSON & CSV (CSV supports strong ETag/304)

1) Import the OpenAPI​

Option A — URL (recommended)

  1. Open Postman → Import → Link.

  2. Paste the OpenAPI URL:

    https://api.useportpulse.com/openapi.json

  3. Click Import. Postman will create a Collection (and optionally an API entry).

Option B — File

If your network blocks external URLs, use the local schema at static/openapi.json (generated during pnpm build).
In Postman: Import → Files and select that file.

If you imported an API instead of a Collection, also generate a collection from it, or re‑import choosing Collection.

2) Create variables and authorization​

Create either a Collection variable (recommended) or an Environment with:

  • baseUrl → https://api.useportpulse.com
  • apiKey → dev_demo_123 (replace with your live key for production)

Then set collection‑level Authorization:

  1. In the left sidebar, select the PortPulse Collection → Authorization tab.
  2. Type: API Key
  3. Key: X-API-Key
  4. Value: {{apiKey}}
  5. Add to: Header
  6. Save. All requests in the collection will inherit this header.

You can also reference the base URL in requests with {{baseUrl}}.

3) Send your first request​

Use the trend endpoint:

Request

GET {{baseUrl}}/v1/ports/USLAX/trend?days=14
Header: X-API-Key: {{apiKey}}

Expected (200 OK, JSON)

[
  { "date": "2025-08-01", "congestion_score": 0.45, "as_of": "2025-08-01T12:00:00Z" }
]

To request CSV, append &format=csv.

4) Optional — CSV ETag / 304 workflow​

Use Postman’s Tests to save the ETag header from a CSV response and perform a conditional GET next time.

Tests tab (on the CSV request)

const etag = pm.response.headers.get('ETag');
if (etag) {
  pm.environment.set('pp_etag', etag);
}

Next request header

If-None-Match: {{pp_etag}}

If data hasn’t changed, the API returns 304 Not Modified. This saves bandwidth and improves latency.

Troubleshooting​

  • 401 / 403 → Check X-API-Key and key scope. See Authentication.
  • 404 → Verify the path and UN/LOCODE (e.g., USLAX). See API Endpoints.
  • 429 → You’re being rate limited. See Rate limits.
  • Error body → Unified JSON: {code, message, request_id, hint}. See Errors.

Next steps​

Download collection​