Getting Started with USPS API

Introduction

Contact Us: USPS API Support | Terms of Service

The Addresses API validates and corrects address information to improve package delivery service and pricing. This suite of APIs provides different utilities for addressing components. The ZIP Code™ lookup finds valid ZIP Code™(s) for a City and State. The City/State lookup provides the valid cities and states for a provided ZIP Code™. The Address Standardization API validates and standardizes USPS® domestic addresses, city and state names, and ZIP Code™ in accordance with USPS® addressing standards. The USPS® address standard includes the ZIP + 4®, signifying a USPS® delivery point, given a street address, a city and a state.

Install the Package

Run the following command from your project directory to install the package from npm:

npm install [email protected]

For additional package details, see the Npm page for the [email protected] npm.

Initialize the API Client

Note: Documentation for the client can be found here.

The following parameters are configurable for the API Client:

| Parameter | Type | Description | | --- | --- | --- | | environment | Environment | The API environment. Default: Environment.Production | | timeout | number | Timeout for API calls.Default: 30000 | | httpClientOptions | Partial<HttpClientOptions> | Stable configurable http client options. | | unstableHttpClientOptions | any | Unstable configurable http client options. | | logging | PartialLoggingOptions | Logging Configuration to enable logging | | oauthAuthorizationCodeCredentials | OauthAuthorizationCodeCredentials | The credential object for oauthAuthorizationCode | | oauthClientCredentialsCredentials | OauthClientCredentialsCredentials | The credential object for oauthClientCredentials | | basicAuthCredentials | BasicAuthCredentials | The credential object for basicAuth | | bearerTokenAuthCredentials | BearerTokenAuthCredentials | The credential object for bearerTokenAuth |

The API client can be initialized as follows:

Code-Based Client Initialization

import {
  Client,
  Environment,
  LogLevel,
  OauthScopeOauthAuthorizationCode,
  OauthScopeOauthClientCredentials,
} from 'apimatic-usps-sdk';

const client = new Client({
  oauthAuthorizationCodeCredentials: {
    oauthClientId: 'OAuthClientId',
    oauthClientSecret: 'OAuthClientSecret',
    oauthRedirectUri: 'OAuthRedirectUri',
    oauthScopes: [
      OauthScopeOauthAuthorizationCode.Addresses,
      OauthScopeOauthAuthorizationCode.Adjustments
    ]
  },
  oauthClientCredentialsCredentials: {
    oauthClientId: 'OAuthClientId',
    oauthClientSecret: 'OAuthClientSecret',
    oauthScopes: [
      OauthScopeOauthClientCredentials.Addresses,
      OauthScopeOauthClientCredentials.Adjustments
    ]
  },
  basicAuthCredentials: {
    username: 'Username',
    password: 'Password'
  },
  bearerTokenAuthCredentials: {
    accessToken: 'AccessToken'
  },
  timeout: 30000,
  environment: Environment.Production,
  logging: {
    logLevel: LogLevel.Info,
    logRequest: {
      logBody: true
    },
    logResponse: {
      logHeaders: true
    }
  },
});

Configuration-Based Client Initialization

import * as path from 'path';
import * as fs from 'fs';
import { Client } from 'apimatic-usps-sdk';

// Provide absolute path for the configuration file
const absolutePath = path.resolve('./config.json');

// Read the configuration file content
const fileContent = fs.readFileSync(absolutePath, 'utf-8');

// Initialize client from JSON configuration content
const client = Client.fromJsonConfig(fileContent);

See the Configuration-Based Client Initialization section for details.

Environment-Based Client Initialization

import * as dotenv from 'dotenv';
import * as path from 'path';
import * as fs from 'fs';
import { Client } from 'apimatic-usps-sdk';

// Optional - Provide absolute path for the .env file
const absolutePath = path.resolve('./.env');

if (fs.existsSync(absolutePath)) {
  // Load environment variables from .env file
  dotenv.config({ path: absolutePath, override: true });
}

// Initialize client using environment variables
const client = Client.fromEnvironment(process.env);

See the Environment-Based Client Initialization section for details.

Environments

The SDK can be configured to use a different environment for making API calls. Available environments are:

Fields

| Name | Description | | --- | --- | | Production | Default | | Testing | - |

Authorization

This API uses the following authentication schemes.

• OAuth_authorization_code (OAuth 2 Authorization Code Grant)
• OAuth_client_credentials (OAuth 2 Client Credentials Grant)
• BasicAuth (Basic Authentication)
• BearerTokenAuth (OAuth 2 Bearer token)

List of APIs

• Listener URL Specification
• Resources
• Files

SDK Infrastructure

Configuration

• HttpClientOptions
• RetryConfiguration
• ProxySettings
• Configuration-Based Client Initialization
• Environment-Based Client Initialization
• PartialLoggingOptions
• PartialRequestLoggingOptions
• PartialResponseLoggingOptions
• LoggerInterface

HTTP

• HttpRequest

Utilities

• ApiResponse
• ApiError