usps-enhanced-addresses-v3r2.yaml

openapi: 3.0.1
info:
  title: Addresses
  description: |
    Contact Us: [USPS API Support](https://emailus.usps.com/s/usps-APIs) | [Terms of Service](https://about.usps.com/termsofuse.htm)
    
    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.
    
  version: 3.3.1
servers:
  - url: https://apis.usps.com/addresses/v3
    description: Production Environment Endpoint
  - url: https://apis-tem.usps.com/addresses/v3
    description: Testing Environment Endpoint
paths:
  /address:
    get:
      tags:
        - Resources
      summary: Returns the best standardized address for a given address.
      description: |-
        Standardizes street addresses including city and street abbreviations as well as providing missing information such as ZIP Code™ and ZIP + 4®.

        Must specify a street address, and either a city and state, or a ZIP Code™ (or all three).
      operationId: get-address
      parameters:
        - name: firm
          in: query
          description: "Firm/business corresponding to the address."
          schema:
            type: string
            maxLength: 50
            minLength: 0
        - name: streetAddress
          in: query
          description: The number of a building along with the name of the road or street on which it is located. This may also contain secondary address information instead of being separate in the secondaryAddress field.
          required: true
          schema:
            type: string
        - name: secondaryAddress
          in: query
          description: The secondary unit designator, such as apartment (APT) or suite (STE), along with the APT/STE value, defining the exact location of the address within a building. This information can be added to the end of the `streetAddress` field instead of separated to this field.  For more information please see [Postal Explorer](https://pe.usps.com/text/pub28/28c2_003.htm).
          required: false
          schema:
            type: string
        - name: city
          in: query
          description: This is the city name of the address.
          required: false
          schema:
            type: string
        - name: state
          in: query
          description: The two-character state code of the address.
          required: false
          schema:
            maxLength: 2
            minLength: 2
            pattern: ^(?:AA|AE|AL|AK|AP|AS|AZ|AR|CA|CO|CT|DE|DC|FM|FL|GA|GU|HI|ID|IL|IN|IA|KS|KY|LA|ME|MH|MD|MA|MI|MN|MS|MO|MP|MT|NE|NV|NH|NJ|NM|NY|NC|ND|OH|OK|OR|PW|PA|PR|RI|SC|SD|TN|TX|UT|VT|VI|VA|WA|WV|WI|WY)$
            type: string
        - name: urbanization
          in: query
          description: This is the urbanization code relevant only for Puerto Rico addresses.
          required: false
          schema:
            type: string
        - name: ZIPCode
          in: query
          description: This is the 5-digit ZIP code.
          required: false
          schema:
            pattern: "^\\d{5}$"
            type: string
        - name: ZIPPlus4
          in: query
          description: This is the 4-digit component of the ZIP+4 code. Using the correct ZIP+4 reduces the number of times your mail is handled and can decrease the chance of a misdelivery or error.
          required: false
          schema:
            pattern: "^\\d{4}$"
            type: string
      x-anyOf-required:
        - required:
            - city
            - state
        - required:
            - ZIPCode
      responses:
        "200":
          description: Successful operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddressResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/AddressResponse'
        "400":
          description: Bad Request. There is an error in the received request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        "401":
          description: Unauthorized request.
          headers:
            WWW-Authenticate:
              $ref: '#/components/headers/WWWAuthenticate'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        "403":
          description: Access is denied.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        "404":
          description: Address Not Found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
              examples:
                Address Not Found:
                  $ref: '#/components/examples/Address-Not-Found'
                No Match:
                  $ref: '#/components/examples/No-Match'
                Invalid State Code:
                  $ref: '#/components/examples/Invalid-State-Code'
                Invalid City:
                  $ref: '#/components/examples/Invalid-City'
                Unverifiable City and State:
                  $ref: '#/components/examples/Unverifiable-City-and-State'
                Insufficient Address Data:
                  $ref: '#/components/examples/Insufficient-Adddress-Data'
                Invalid Delivery Address:
                  $ref: '#/components/examples/Invalid-Delivery-Address'
                Multiple Addresses Found:
                  $ref: '#/components/examples/Multiple-Addresses-Found'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        "429":
          description: Too Many Requests. Too many requests have been received from the client in a short amount of time.
          headers:
            Retry-After:
              $ref: '#/components/headers/RetryAfter'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        "503":
          description: Service is unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        default:
          description: Other unanticipated errors that may occur.
          content: {}
      security:
        - OAuth:
            - addresses
  /city-state:
    get:
      tags:
        - Resources
      summary: Returns the city and state for a given ZIP Code.
      description: Returns the city and state corresponding to the given ZIP Code™.
      operationId: get-city-state
      parameters:
        - name: ZIPCode
          in: query
          description: This is the 5-digit ZIP code.
          required: true
          schema:
            pattern: "^\\d{5}$"
            type: string
      responses:
        "200":
          description: Successful operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CityStateResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/CityStateResponse'
        "400":
          description: A bad request was received.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        "401":
          description: Unauthorized request.
          headers:
            WWW-Authenticate:
              $ref: '#/components/headers/WWWAuthenticate'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        "403":
          description: Access is denied.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        "429":
          description: Too Many Requests. Too many requests have been received from the client in a short amount of time.
          headers:
            Retry-After:
              $ref: '#/components/headers/RetryAfter'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        "503":
          description: Service is unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        default:
          description: Other unanticipated errors that may occur.
          content: {}
      security:
        - OAuth:
            - addresses
  /zipcode:
    get:
      tags:
        - Resources
      summary: Returns the ZIP Code for a given address.
      description: "Returns the ZIP Code™ and ZIP + 4® corresponding to the given address, city, and state (use USPS state abbreviations)."
      operationId: get-ZIPCode
      parameters:
        - name: firm
          in: query
          description: "Firm/business corresponding to the address."
          schema:
            type: string
            maxLength: 50
            minLength: 0
        - name: streetAddress
          in: query
          description: The number of a building along with the name of the road or street on which it is located. This may also contain secondary address information when it is used to provide a standardized address or is provided in the associated request field.
          required: true
          schema:
            type: string
        - name: secondaryAddress
          in: query
          description: The secondary unit designator, such as apartment (APT) or suite (STE), along with the APT/STE value, defining the exact location of the address within a building. Information initially entered on the secondaryAddress request field may not appear in the response secondaryAddress field when it’s used to provide a standardized address (see streetAddress). This field may also contain information when it does not contain address information (e.g., c/o or ATTN information). For more information please see [Postal Explorer](https://pe.usps.com/text/pub28/28c2_003.htm).
          required: false
          schema:
            type: string
        - name: city
          in: query
          description: This is the city name of the address.
          required: true
          schema:
            type: string
        - name: state
          in: query
          description: This is the two-character state code of the address.
          required: true
          schema:
            maxLength: 2
            minLength: 2
            pattern: ^(AA|AE|AL|AK|AP|AS|AZ|AR|CA|CO|CT|DE|DC|FM|FL|GA|GU|HI|ID|IL|IN|IA|KS|KY|LA|ME|MH|MD|MA|MI|MN|MS|MO|MP|MT|NE|NV|NH|NJ|NM|NY|NC|ND|OH|OK|OR|PW|PA|PR|RI|SC|SD|TN|TX|UT|VT|VI|VA|WA|WV|WI|WY)$
            type: string
        - name: ZIPCode
          in: query
          description: This is the 5-digit ZIP code.
          required: false
          schema:
            pattern: "^\\d{5}$"
            type: string
        - name: ZIPPlus4
          in: query
          description: This is the 4-digit component of the ZIP+4 code. Using the correct ZIP+4 reduces the number of times your mail is handled and can decrease the chance of a misdelivery or error.
          required: false
          schema:
            pattern: "^\\d{4}$"
            type: string
      responses:
        "200":
          description: Successful operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZIPCodeResponse'
            application/xml:
              schema:
                $ref: '#/components/schemas/ZIPCodeResponse'
        "400":
          description: There is an error in the received request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        "401":
          description: Unauthorized request.
          headers:
            WWW-Authenticate:
              $ref: '#/components/headers/WWWAuthenticate'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        "403":
          description: Access is denied.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        "429":
          description: Too Many Requests. Too many requests have been received from the client in a short amount of time.
          headers:
            Retry-After:
              $ref: '#/components/headers/RetryAfter'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        "503":
          description: Service is unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        default:
          description: Other unanticipated errors that may occur.
          content: {}
      security:
        - OAuth:
            - addresses
components:
  schemas:
    AddressResponse:
      title: Address Response
      type: object
      properties:
        firm:
          maxLength: 50
          minLength: 0
          type: string
          description: This is the firm/business name at the address.
        address:
          $ref: '#/components/schemas/DomesticAddress'
        additionalInfo:
          $ref: '#/components/schemas/AddressAdditionalInfo'
        corrections:
          $ref: '#/components/schemas/AddressCorrections'
        matches:
          $ref: '#/components/schemas/AddressMatches'
        warnings:
          type: array
          xml:
            wrapped: true
          items:
            type: string
            xml:
              name: warning
      additionalProperties: false
      description: "Standardizes street addresses including city and street abbreviations, and provides missing information such as ZIP Code™ and ZIP + 4®."
      xml:
        name: AddressValidateResponse
        wrapped: true
    CityAndState:
      title: City And State
      type: object
      properties:
        city:
          maxLength: 28
          minLength: 1
          type: string
          description: This is the city name of the address.
          example: "Des Moines"
        state:
          maxLength: 2
          minLength: 2
          pattern: "\\w{2}"
          type: string
          description: This is two-character state code of the address.
          example: IA
        ZIPCode:
          maxLength: 5
          minLength: 5
          type: string
          description: This is the ZIP Code of the address.
          example: "50314"
    AddressCorrections:
      title: Address Corrections
      type: array
      description: |
        Codes that indicate how to improve the address input to get a better match.
        
        Code `32` will indicate "Default address: The address you entered was found but more information is needed (such as an apartment, suite, or box number." The recommended change would be to add additional information, such as an apartment, suite, or box number, to match to a specific address.
        
        Code `22` will indicate "Multiple addresses were found for the information you entered, and no default exists." The address could not be resolved as entered and more information would be needed to identify the address.
      xml:
        name: addressCorrections
        wrapped: true
      items:
        type: object
        properties:
          code:
            maxLength: 2
            minLength: 1
            pattern: "\\w{2}"
            type: string
            description: The code corresponding to the address correction.
            xml:
              name: code
          text:
            type: string
            description: This is the description of the address correction.
            xml:
              name: text
        additionalProperties: false
        xml:
          name: addressCorrection
    AddressMatches:
      title: Address Matches
      type: array
      description: |
        Codes that indicate if an address is an exact match.
        
        Code `31` will be returned "Single Response - exact match" indicating that the address was correctly matched to a ZIP+4 record.
      xml:
        name: addressMatches
        wrapped: true
      items:
        type: object
        properties:
          code:
            maxLength: 2
            minLength: 1
            pattern: "\\w{2}"
            type: string
            xml:
              name: code
          text:
            type: string
            xml:
              name: text
        additionalProperties: false
        xml:
          name: addressMatch
    AddressAdditionalInfo:
      title: Address Additional Information
      type: object
      properties:
        deliveryPoint:
          type: string
          description: |-
            A specific set of digits between 00 and 99 is assigned to every address that is combined with the ZIP + 4® Code to provide a unique identifier for every delivery address.

            A street address does not necessarily represent a single delivery point because a street address such as one for an apartment building may have several delivery points.
        carrierRoute:
          maxLength: 5
          minLength: 0
          type: string
          description: This is the carrier route code (values unspecified).
          example: "C012"
        countyName:
          maxLength: 25
          minLength: 0
          type: string
          description: This is the county name associated with the delivery point (values unspecified).
          example: "SHELBY"
        congressDistrict:
          maxLength: 2
          minLength: 0
          type: string
          description: This is the congressional district number associated with the address. In some cases, it will be "AL" for At-Large.
          example: "01"
        footnotes:
          maxLength: 32
          minLength: 0
          type: string
          description: The address footnotes.
        recordType:
          maxLength: 1
          minLength: 0
          type: string
          description: |
           The record type of the ZIP + 4® match.
            * `G` - General Delivery
            * `P` - PO Box
            * `R` - Rural Route/Highway Contract
            * `H` - Highrise
            * `F` - Firm
            * `S` - Street
          enum:
            - "G"
            - "P"
            - "R"
            - "H"
            - "F"
            - "S"
        secondaryInfo:
          maxLength: 30
          minLength: 0
          type: string
          description: The extracted secondary information from the streetAddress field.
        returnCode:
          type: number
          description: |
            The return code from the address match.
            * `32` - Default Match
            * `31` - Single Match
            * `22` - Multiple Response Match
            * `21` - Address Not Found
            * `13` - Invalid City
            * `12` - Invalid State Code
            * `11` - Invalid ZIP Code
            * `10` - Invalid Address
          enum:
            - 32
            - 31
            - 22
            - 21
            - 13
            - 12
            - 11
            - 10
        returnCodeText:
          type: string
          description: |
              This is a description of the return code
              * "Default address: The address you entered was found but more information is needed (such as an apartment, suite, or box number) to match to a specific address"
              * "Single Response – exact match"
              * "Multiple addresses were found for the information you entered, and no default exists."
              * "Address Not Found"
              * "Invalid City"
              * "Invalid State Code"
              * "Invalid ZIP Code"
              * "Invalid Address"
        DPVConfirmation:
          type: string
          description: |
            The DPV Confirmation indicator identifies whether the address provided maps to a known USPS address record, whether the USPS delivers to the address or not. If the USPS does not deliver to the address, the USPS may deliver to a PO Box instead. `carrierRoute` values of `R777` and `R779`, for example, may require the shipper to ask the recipient where they receive their USPS mail, which may be different than their physical address.
            * `Y` - Address was DPV confirmed for both primary and (if present) secondary numbers.  A value of `Y` does not necessarily imply that USPS delivers to that address.
            * `D` - Address was DPV confirmed for the primary number only, and the secondary number information was missing.
            * `S` - Address was DPV confirmed for the primary number only, and the secondary number information was present but not confirmed.
            * `N` - Both primary and (if present) secondary number information failed to DPV confirm.
          enum:
            - "Y"
            - "D"
            - "S"
            - "N"
        DPVEnhancedConfirmation:
          type: string
          description: |-
            The DPV Confirmation indicator identifies whether the address is delivered to by the USPS.
            * `Y` - All components confirmed.
            * `D` - Secondary was dropped or trailing alpha on primary was dropped to confirm.
            * `S` - Address confirmed on primary number but secondary number required for complete address.
            * `R` - Address DPV Confirmed but USPS does not deliver to the address.
            * `N` - Primary number not confirmed.
          enum:
            - "Y"
            - "D"
            - "S"
            - "R"
            - "N"
        DPVFootnotes:
          type: string
          maxLength: 10
          minLength: 0
          description: The footnotes associated with the DPV information.
        business:
          type: string
          deprecated: true
          description: |
            Indicates whether this is a business address.
            * `Y` - The address is a business address.
            * `N` - The address is not a business address.
          enum:
            - "Y"
            - "N"
        DPVBusiness:
          type: string
          description: |
            Indicates whether this is a business address.
            * `Y` - The address is a business address.
            * `N` - The address is not a business address.
          enum:
            - "Y"
            - "N"
        DPVCMRA:
          type: string
          description: |-
            Indicates if the location is a [Commercial Mail Receiving Agency (CMRA)](https://faq.usps.com/s/article/Commercial-Mail-Receiving-Agency-CMRA).
             * `Y` - Address was found in the CMRA table.
             * `N` - Address was not found in the CMRA table.
          enum:
            - "Y"
            - "N"
        DPVDrop:
          type: string
          description: |
            Indicates whether the address is a drop (mail is dropped off for more than 1 customer).
             * `Y` - Address is a drop.
             * `N` - Address is not a drop.
          enum:
            - "Y"
            - "N"
        DPVEducational:
          type: string
          description: |
            Indicates whether the address is an educational location.
             * `Y` - Address is educational.
             * `N` - Address is not educational.
          enum:
            - "Y"
            - "N"
        DPVDropCount:
          type: string
          maxLength: 3
          minLength: 0
          description: Indicates how many customers receive mail at a drop address or CMRA.
          example: "002"
        DPVLACS:
          type: string
          description: |
            Indicates whether the address is an old side LACS address.
             * `Y` - Address is a LACS address.
             * `N` - Address is not a LACS address.
          enum:
            - "Y"
            - "N"
        DPVNoDoorDelivery:
          type: string
          description: |
            Indicates whether the address does not allow delivery at the door.
             * `Y` - Address does not allow door delivery.
             * `N` - Address allows door delivery.
          enum:
            - "Y"
            - "N"
        DPVPBSA:
          type: string
          description: |
            Indicates whether the address is a PO Box Street Address.
             * `Y` - Address is a PBSA.
             * `N` - Address is not a PBSA.
          enum:
            - "Y"
            - "N"
        DPVNostatReasonCode:
          type: string
          description: |
            Indicates the reason code for nostat flag.
             * `1` - IDA (Internal Drop Address) - Addresses that do not receive mail directly from the USPS but are delivered to a drop address that services them (e.g., gated community).
             * `2` - CDS Nostat - Addresses that have not yet become deliverable. For example, a new subdivision where lots and primary numbers have been determined, but no structure exists yet for occupancy.
             * `4` - CMZ Nostat - College, military, and other types. ZIP + 4® records USPS has incorporated into the data.
             * `5` - Regular nostat - Indicates addresses not receiving delivery and the addresses are not counted as possible deliveries.
             * `6` - Secondary Required - The address requires secondary information (unconfirmed secondary entered or secondary missing).
          enum:
            - "1"
            - "2"
            - "4"
            - "5"
            - "6"            
        DPVNostatReasonCodeDesc:
          type: string
          description: |
           Indicates the reason description for nostat flag.
            * "IDA (Internal Drop Address)"
            * "CDS Nostat"
            * "CMZ Nostat"
            * "Regular Nostat"
            * "Secondary Required"
          enum:
            - "INTERNAL_DROP_ADDRESS"
            - "CDS_NOSTAT"
            - "CMZ_NOSTAT"
            - "REGULAR_NOSTAT"
            - "SECONDARY_REQUIRED"                      
        centralDeliveryPoint:
          type: string
          description: |
            Central Delivery is for all business office buildings and/or industrial/professional parks. This may include call windows, horizontal locked mail receptacles, and cluster box units.
            * `Y` - The address is a central delivery point.
            * `N` - The address is not a central delivery point.
          enum:
            - "Y"
            - "N"
        DPVSeasonal:
          type: string
          description: |
           Indicates the address is seasonal.
            * `Y` - The address is seasonal.
            * `N` - The address is not seasonal.
          enum:
            - "Y"
            - "N"
        DPVThrowback:
          type: string
          description: |
           Indicates the address is a throwback (actual delivery is to a PO Box).
            * `Y` - The address is a throwback.
            * `N` - The address is not a throwback.
          enum:
            - "Y"
            - "N"
        DPVNoSecureLocation:
          type: string
          description: |
           Indicates the address is flagged as not a secure location.
            * `Y` - The address is flagged as not a secure location.
            * `N` - The address is not flagged as not a secure location.
          enum:
            - "Y"
            - "N"
        vacant:
          type: string
          description: |
            Indicates whether the location designated by the address is occupied.
            * `Y` - The address is not occupied.
            * `N` - The address is occupied.
          enum:
            - "Y"
            - "N"
        DPVVacant:
          type: string
          description: |
           Indicates whether the location designated by the address is occupied.
            * `Y` - The address is not occupied.
            * `N` - The address is occupied.
          enum:
            - "Y"
            - "N"
        DPVNostat:
          type: string
          description: |
           Indicates the address is not counted for statistical purposes.
            * `Y` - The address is a nostat.
            * `N` - The address is not a nostat.
          enum:
            - "Y"
            - "N"
        DPVNonDeliveryDaysFlag:
          type: string
          description: |
           Indicates the address doesn't have mail delivered on one or more days.
            * `Y` - The address has non-delivery days.
            * `N` - The address doesn't have non-delivery days.
          enum:
            - "Y"
            - "N"
        DPVNonDeliveryDaysSMTWTFS:
          type: string
          description: Indicates the days the mail is not delivered in SMTWTFS string of characters. These values are positional. If a day has mail delivered, it is a space in that day's position.
        DPVNonDeliveryDaysValues:
          type: array
          description: Delivery Point Validation on non delivery days, returned as an array of strings
          items:
            type: string
            description: Array of strings of non-delivery days
          example:
            - Sunday
            - Friday
            - Saturday
        DPVCurbDelivery:
          type: string
          description: |
           Indicates the address mail delivery is curb.
            * `Y` - The address has curb delivery.
            * `N` - The address doesn't have curb delivery.
          enum:
            - "Y"
            - "N"
        DPVCentralBoxDelivery:
          type: string
          description: |
           Indicates the address mail delivery is central box.
            * `Y` - The address has central box delivery.
            * `N` - The address doesn't have central box delivery.
          enum:
            - "Y"
            - "N"
        DPVNDCBUDelivery:
          type: string
          description: |
           Indicates the address mail delivery is NDCBU.
            * `Y` - The address has NDCBU delivery.
            * `N` - The address doesn't have NDCBU delivery.
          enum:
            - "Y"
            - "N"
        DPVOtherDelivery:
          type: string
          description: |
           Indicates the address mail delivery is other.
            * `Y` - The address has other delivery.
            * `N` - The address doesn't have other delivery.
          enum:
            - "Y"
            - "N"
        DPVDeliveryType:
          type: string
          description: |
           Indicates the delivery type.
            * `1` - The address has curb delivery.
            * `2` - The address has NDCBU delivery.
            * `3` - The address has central box delivery.
            * `4` - The address has other delivery.
          enum:
            - "1"
            - "2"
            - "3"
            - "4"      
        DPVUsageCode:
          type: string
          description: |
           Indicates when usage is mixed business/residential.
            * `A` - The address is residential.
            * `B` - The address is business.
            * `C` - The address mixed residential/business, but mostly residential.
            * `D` - The address mixed residential/business, but mostly business.
            * `G` - The address is General Delivery.
            * ` ` - The address has no usage code assigned.
          enum:
            - "A"
            - "B"
            - "C"
            - "D"
            - "G"
            - " "            
        electricVehicleRoute:
          type: boolean
          description: |
           Denotes if the carrier route associated with the address has electric vehicles.
            * true - The carrier route has electric vehicles
            * false - The carrier route does not have electric vehicles
          enum:
            - true
            - false
        postOfficeCity:
          type: string
          description: The city associated with the delivery post office.
        postOfficeState:
          type: string
          description: The state associated with the delivery post office.
        countyNumber:
          type: string
          description: The county number for the address.
        autoZoneIndicator:
          type: string
          description: |
           The automated zone indicator for the delivery unit.
            * `A` - Carrier Route Sort Rates Apply - Merge Allowed.
            * `B` - Carrier Route Sort Rates Apply - Merge Not Allowed.
            * `C` - Carrier Route Sort Rates Do Not Apply - Merge Allowed.
            * `D` - Carrier Route Sort Rates Do Not Apply - Merge Not Allowed.
          enum:
            - "A"
            - "B"
            - "C"
            - "D"
        LACSLinkReturnCode:
          type: string
          description: |
           The return code from the LACSLink inquiry.
            * `00` - LACSLink no match.
            * `14` - Multiple LACSLink addresses found, unable to break tie.
            * `A`  - LACSLink address converted without modifications.
            * `92` - LACSLink address converted but secondary dropped.
          enum:
            - "00"
            - "14"
            - "A"
            - "92"
        LACSLinkIndicator:
          type: string
          description: |
           Indicates if a match was found from LACSLink.
            * `Y` - LACSLink address found.
            * `N` - LACSLink address not found.
            * `S` - LACSLink address converted but secondary dropped.
            * `F` - LACSLink false positive address encountered.
          enum:
            - "Y"
            - "N"
            - "S"
            - "F"
        miscLine:
          type: string
          description: Extraneous information removed from the address line not used to match the address.
        ZIP5Valid:
          type: string
          description: |
           Indicates if the returned ZIP Code corresponds to the returned City/State.
            * `Y` - The ZIP Code matches the City/State.
            * `N` - The ZIP Code doesn't match the City/State.
          enum:
            - "Y"
            - "N"
        POBoxOnlyZIP:
          type: string
          description: |
           Indicates if the returned ZIP Code facility only serves PO Box addresses.
            * `Y` - The ZIP Code facility only serves PO Box addresses.
            * `N` - The ZIP Code facility serves non-PO Box addresses.
          enum:
            - "Y"
            - "N"
        defaultFlag:
          type: string
          description: |
           Indicates the address matched is a default.
            * `Y` - The address matched is a default.
            * `N` - The address matched is not a default.
          enum:
            - "Y"
            - "N"
        matchedPrimaryNumber:
          type: string
          description: The value of the matched primary number.
        matchedSecondaryNumber:
          type: string
          description: The value of the matched secondary number.
        parsedPMBDesignator:
          type: string
          description: The value of the parsed PMB Designator.
        parsedPMBNumber:
          type: string
          description: The value of the PMB number.
        suiteLinkIndicator:
          type: string
          description: |
           Indicates if a match was found from SuiteLink.
            * `00` - SuiteLink no match.
            * `A`  - SuiteLink match.
          enum:
            - "00"
            - "A"
        financeNumber:
          type: string
          description: Finance number associated with address.
        baseAlternateCode:
          type: string
          description: |
           Base/Alternate code associated with ZIP + 4® record.
            * `A` - Alternate record.
            * `B` - Base record.
          enum:
            - "A"
            - "B"
        LACSIndicator:
          type: string
          description: |
           LACS Indicator associated with ZIP + 4® record.
            * `L` - LACS Indicator present.
            * ``  - LACS Indicator not present.
          enum:
            - "L"
            - ""
        eLOTCode:
          type: string
          description: |
           eLOT Ascending/Descending Code
            * `A` - eLOT Number Ascending
            * `D` - eLOT Number Descending
          enum:
            - "A"
            - "D"
        eLOTNumber:
          type: string
          maxLength: 4
          minLength: 0
          description: eLOT Number
          example: "0100"
      additionalProperties: false
      description: Extra information about the request.
      xml:
        name: addressAdditionalInfo
    CityStateResponse:
      title: City and State Response
      description: The validated ZIP Code™ for a given city and state.
      xml:
        name: CityStateLookupResponse
        wrapped: true
      allOf:
        - $ref: '#/components/schemas/CityAndState'
    ZIPCodeResponse:
      title: ZIP Code™ Response
      type: object
      properties:
        firm:
          maxLength: 50
          minLength: 0
          type: string
          description: This is the firm/business name at the address.
        address:
          $ref: '#/components/schemas/DomesticAddress'
      additionalProperties: false
      description: The address to validate the ZIP Code™ for.
      xml:
        name: ZipCodeLookupResponse
        wrapped: true
    ErrorMessage:
      title: Error
      type: object
      properties:
        apiVersion:
          type: string
          description: The version of the API that was used and that raised the error.
        error:
          type: object
          properties:
            code:
              type: string
              description: The error status code that has been returned in response to the request.
            message:
              type: string
              description: A human-readable message describing the error.
            errors:
              type: array
              items:
                type: object
                properties:
                  status:
                    type: string
                    description: The status code response returned to the client.
                  code:
                    type: string
                    description: An internal subordinate code used for error diagnosis.
                  title:
                    type: string
                    description: A human-readable title that identifies the error.
                  detail:
                    type: string
                    description: A human-readable description of the error that occurred.
                  source:
                    type: object
                    properties:
                      parameter:
                        type: string
                        description: The input in the request which caused an error.
                      example:
                        type: string
                        description: An example of a valid value for the input parameter.
                    additionalProperties: true
                    description: The element that is suspected of originating the error.  Helps to pinpoint the problem.
                additionalProperties: true
          additionalProperties: true
          description: The high-level error that has occurred as indicated by the status code.
      additionalProperties: true
      description: Standard error message response.
    DomesticAddress:
      title: Domestic Address
      additionalProperties: true
      description: Address fields for US locations
      allOf:
        - $ref: '#/components/schemas/Address'
        - type: object
          properties:
            city:
              maxLength: 28
              minLength: 1
              type: string
              description: This is the city name of the address.
            state:
              $ref: '#/components/schemas/State'
            ZIPCode:
              pattern: "\\d{5}"
              type: string
              description: This is the 5-digit ZIP code.
            ZIPPlus4:
              pattern: "\\d{4}"
              type: string
              description: This is the 4-digit component of the ZIP+4 code. Using the correct ZIP+4 reduces the number of times your mail is handled and can decrease the chance of a misdelivery or error.
              nullable: true
            urbanization:
              maxLength: 96
              type: string
              description: "An area, sector, or residential development within a geographic area (currently only used for addresses in Puerto Rico)."
            lastline:
              type: string
              description: This is the lastline information (City/State/ZIP Code, where available) without the abbreviated City name.
            lastlineAbbr:
              type: string
              description: This is the lastline information (City/State/ZIP Code, where available) with the abbreviated City name.
          additionalProperties: true
    Address:
      title: Address
      type: object
      properties:
        streetAddress:
          maxLength: 50
          minLength: 1
          type: string
          description: The number of a building along with the name of the road or street on which it is located. This may also contain secondary address information when it is used to provide a standardized address.
        streetAddressAbbreviation:
          maxLength: 50
          minLength: 0
          type: string
          description: This is the abbreviation of the primary street address line for the address.
          readOnly: true
        secondaryAddress:
          maxLength: 50
          type: string
          description: The secondary unit designator, such as apartment (APT) or suite (STE), along with the APT/STE value, defining the exact location of the address within a building. Information initially entered on the secondaryAddress request field may not appear in the response secondaryAddress field when it's used to provide a standardized address (see streetAddress). This field may also contain information provided on the request secondaryAddress when it does not contain address information (e.g., c/o or ATTN information).
        cityAbbreviation:
          type: string
          description: This is the abbreviation of the city name for the address.
          readOnly: true
      additionalProperties: true
      description: Address fields standard to all locations.
      xml:
        name: Address
    State:
      maxLength: 2
      minLength: 2
      pattern: ^(?:AA|AE|AL|AK|AP|AS|AZ|AR|CA|CO|CT|DE|DC|FM|FL|GA|GU|HI|ID|IL|IN|IA|KS|KY|LA|ME|MH|MD|MA|MI|MN|MS|MO|MP|MT|NE|NV|NH|NJ|NM|NY|NC|ND|OH|OK|OR|PW|PA|PR|RI|SC|SD|TN|TX|UT|VT|VI|VA|WA|WV|WI|WY)$
      type: string
      description: The two-character state code.
  parameters:
    StreetAddress-Required:
      name: streetAddress
      in: query
      description: The number of a building along with the name of the road or street on which it is located.
      required: true
      schema:
        type: string
    SecondaryAddress:
      name: secondaryAddress
      in: query
      description: "The secondary unit designator, such as apartment(APT) or suite(STE) number, defining the exact location of the address within a building.  For more information please see [Postal Explorer](https://pe.usps.com/text/pub28/28c2_003.htm)."
      required: false
      schema:
        type: string
    City:
      name: city
      in: query
      description: This is the city name of the address.
      required: false
      schema:
        type: string
    State-Required:
      name: state
      in: query
      description: This is two-character state code of the address.
      required: false
      schema:
        maxLength: 2
        minLength: 2
        pattern: ^(?:AA|AE|AL|AK|AP|AS|AZ|AR|CA|CO|CT|DE|DC|FM|FL|GA|GU|HI|ID|IL|IN|IA|KS|KY|LA|ME|MH|MD|MA|MI|MN|MS|MO|MP|MT|NE|NV|NH|NJ|NM|NY|NC|ND|OH|OK|OR|PW|PA|PR|RI|SC|SD|TN|TX|UT|VT|VI|VA|WA|WV|WI|WY)$
        type: string
    Urbanization:
      name: urbanization
      in: query
      description: This is the urbanization code relevant only for Puerto Rico addresses.
      required: false
      schema:
        type: string
    ZIPCode:
      name: ZIPCode
      in: query
      description: This is the 5-digit ZIP code.
      required: false
      schema:
        pattern: "^\\d{5}$"
        type: string
    ZIPPlus4:
      name: ZIPPlus4
      in: query
      description: This is the 4-digit component of the ZIP+4 code. Using the correct ZIP+4 reduces the number of times your mail is handled and can decrease the chance of a misdelivery or error.
      required: false
      schema:
        pattern: "^\\d{4}$"
        type: string
    ZIPCode-Required:
      name: ZIPCode
      in: query
      description: This is the 5-digit ZIP code.
      required: true
      schema:
        pattern: "^\\d{5}$"
        type: string
    City-Required:
      name: city
      in: query
      description: This is the city name of the address.
      required: true
      schema:
        type: string
  examples:
    Invalid-City:
      summary: The city is missing or invalid.
      description: The city is missing or invalid.
      value:
        apiVersion: v3
        error:
          code: "404"
          message: The city in the request is missing or invalid.
          errors: []
    Invalid-State-Code:
      summary: The two-letter state code is missing or invalid.
      description: The two-letter state code is missing or invalid.
      value:
        apiVersion: v3
        error:
          code: "404"
          message: The state code in the request is missing or invalid.
          errors: []
    Unverifiable-City-and-State:
      summary: The city and state are missing or together unverifiable.
      description: The city and state are missing or together unverifiable.
      value:
        apiVersion: v3
        error:
          code: "404"
          message: The city and state are missing or together unverifiable.
          errors: []
    Insufficient-Adddress-Data:
      summary: The address information in the request is insufficient to match.
      description: The address information in the request is insufficient to match.
      value:
        apiVersion: v3
        error:
          code: "404"
          message: The address information in the request is insufficient to match.
          errors: []
    Address-Not-Found:
      summary: The address requested could not be found.
      description: "There is no match for the specified address, try adding as much information as possible."
      value:
        apiVersion: v3
        error:
          code: "404"
          message: There is no match for the address requested.
          errors: []
    No-Match:
      summary: Could not find any matching address.
      description: "There is no match for the specified address, try adding as much information as possible."
      value:
        apiVersion: v3
        error:
          code: "404"
          message: There is no match for the address requested.
          errors: []
    Invalid-Delivery-Address:
      summary: The address requested is an invalid delivery address.
      description: The address requested is an invalid delivery address.
      value:
        apiVersion: v3
        error:
          code: "404"
          message: The address requested is an invalid delivery address.
          errors: []
    Multiple-Addresses-Found:
      summary: More than one address was found matching the requested address.
      description: More than one address was found matching the requested address.
      value:
        apiVersion: v3
        error:
          code: "404"
          message: More than one address was found matching the requested address.
          errors: []
  headers:
    WWWAuthenticate:
      description: Hint to the client application which security scheme to authorize a resource request.
      required: false
      schema:
        type: string
        example: "WWW-Authenticate: Bearer realm=\"https://api.usps.com\""
    RetryAfter:
      description: Indicate to the client application a time after which they can retry a resource request.
      required: false
      schema:
        type: string
        example: "Retry-After: 30"
  securitySchemes:
    OAuth:
      type: oauth2
      description: The specified APIs accept an access token formatted as a JSON Web Token. The relative path to the OAuth2 version 3 API which supplies this access token is provided below for reference.
      flows:
        clientCredentials:
          tokenUrl: /oauth2/v3/token
          scopes:
            addresses: read-only access to all addresses endpoints
        authorizationCode:
          authorizationUrl: /oauth2/v3/authorize
          tokenUrl: /oauth2/v3/token
          scopes:
            addresses: read-only access to all addresses endpoints