United States Postal Service Files API

openapi: 3.2.0
info:
  title: Usps Files API
  version: '1.0'
  description: 'Operations tagged Files across 3 of this provider''s published API definitions: usps-locations-openapi.yml, usps-locations-openapi.yml, usps-service-standards-files-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://apis.usps.com/locations/v3
  description: Production Environment Endpoint
- url: https://apis-tem.usps.com/locations/v3
  description: Testing Environment Endpoint
- url: https://apis.usps.com/service-standards-files/v3
  description: Primary server endpoint for the Service Standards API that handles file management operations, including listing available files and generating signed URLs for secure downloads.
- url: https://apis-tem.usps.com/service-standards-files/v3
  description: Testing Environment Endpoint
tags:
- name: Files
paths:
  /files:
    get:
      tags:
      - Files
      summary: List available location files for download
      operationId: getLocationFiles
      description: Retrieve a list of location-related files available for download from the Locations API.
      security:
      - OAuth:
        - locations-files
      responses:
        '200':
          description: A list of available location files
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Links'
              examples:
                filesExample:
                  $ref: '#/components/examples/LocationFilesExample'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '401':
          description: Unauthorized request
          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: Resource Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
    servers:
    - url: https://apis.usps.com/locations/v3
      description: Production Environment Endpoint
    - url: https://apis-tem.usps.com/locations/v3
      description: Testing Environment Endpoint
  /files/{fileID}/generate-signed-url:
    get:
      tags:
      - Files
      summary: Generate a signed URL for downloading a location file
      description: Generate a secure, temporary URL for downloading a specific location file using its file ID.
      operationId: generateLocationSignedURL
      parameters:
      - name: fileID
        in: path
        required: true
        schema:
          type: string
          example: PostOfficeLocations_Current
      security:
      - OAuth:
        - locations-files
      responses:
        '200':
          description: Signed URL generated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignedURLResponse'
              examples:
                GenerateSignedURLResponseExample:
                  $ref: '#/components/examples/GenerateLocationSignedURLResponseExample'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '401':
          description: Unauthorized request
          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: Resource Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
    servers:
    - url: https://apis.usps.com/locations/v3
      description: Production Environment Endpoint
    - url: https://apis-tem.usps.com/locations/v3
      description: Testing Environment Endpoint
components:
  examples:
    GenerateLocationSignedURLResponseExample:
      summary: Example response for generating a signed URL for a location file
      value:
        signedURL: https://locations-files.usps.com/download/PostOfficeLocations%2FPostOfficeLocations_05282026.zip?sv=2026-01-05&st=2026-05-28T16%3A10%3A35Z&se=2026-05-29T16%3A15%3A35Z&sr=b&sp=r&sig=i6S%2F9n6VSDehnow0fRUoCPBeKFxUQp3TviZOampup5U%3D
        expiry: '2026-05-29T16:15:35.557196124Z'
        contentLength: 104857600
        rangeLimit: 10485760
    LocationFilesExample:
      summary: List of location files
      description: List of location-related files currently available for download
      value:
      - rel:
        - self
        title: Post Office Locations
        href: https://apis.usps.com/locations-files/v3/files/PostOfficeLocations_Current/generate-signed-url
        method: GET
        targetMediaType: application/zip
        publishDate: 2026-05-28 19:42:28+00:00
    GenerateSignedUrlResponseExample:
      summary: Example response for generating a signed URL
      value:
        signedURL: https://service-standards-files.usps.com/download/Combined_Service_Standard_Directory%2FCombined_Service_Standard_Directory_03112025_PME.zip?sv=2025-01-05&st=2025-03-26T16%3A10%3A35Z&se=2025-03-27T16%3A15%3A35Z&sr=b&sp=r&sig=i6S%2F9n6VSDehnow0fRUoCPBeKFxUQp3TviZOampup5U%3D
        expiry: '2025-06-27T13:22:21.557196124'
        contentLength: 52428800
        rangeLimit: 10485760
    FilesExampleA:
      description: List of files currently available for download
      summary: List of files
      value:
      - rel:
        - self
        title: Complete Service Standard Data
        href: https://apis.usps.com/service-standards-files/files/Combined_Service_Standard_Directory_MKT/generate-signed-url
        method: GET
        targetMediaType: application/zip
        publishDate: 2025-06-12 22:15:23+00:00
      - rel:
        - self
        title: Base Service Standard Data
        href: https://apis.usps.com/service-standards-files/files/Combined_Service_Standard_Directory_PKG/generate-signed-url
        method: GET
        targetMediaType: application/zip
        publishDate: 2025-05-16 16:45:23+00:00
      - rel:
        - self
        title: Service Standard Exception Data
        href: https://apis.usps.com/service-standards-files/files/Combined_Service_Standard_Directory_PME/generate-signed-url
        method: GET
        targetMediaType: application/zip
        publishDate: 2025-03-25 19:25:15+00:00
  schemas:
    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.
    SignedURLResponse:
      title: Signed URL Response
      description: Response containing a signed URL and metadata for downloading a location file.
      type: object
      properties:
        signedURL:
          type: string
          maxLength: 2048
          minLength: 1
          description: 'A fully-qualified SAS URL appended with a secure token that provides temporary, restricted access to the requested location file. This SAS URL supports HTTP Range requests, allowing consumers to download files in chunks. This is particularly useful for resuming interrupted downloads or handling very large files.

            '
          example: https://locations-files.usps.com/download/PostOfficeLocations%2FPostOfficeLocations_05282026.zip?sv=2026-01-05&st=2026-05-28T16%3A10%3A35Z&se=2026-05-29T16%3A15%3A35Z&sr=b&sp=r&sig=i6S%2F9n6VSDehnow0fRUoCPBeKFxUQp3TviZOampup5U%3D
        expiry:
          type: string
          format: date-time
          maxLength: 35
          minLength: 1
          description: Expiration date and time of the signed URL.
        contentLength:
          type: integer
          minimum: 0
          maximum: 107374182400
          description: Size of the file in bytes.
          example: 104857600
        rangeLimit:
          type: integer
          minimum: 0
          maximum: 107374182400
          description: The maximum number of bytes that can be downloaded using the signed URL. This value is specified in bytes and ensures that users do not exceed the allocated download limit.
          example: 10485760
      additionalProperties: false
    Links:
      title: Hypermedia Links
      type: array
      description: Hypermedia links to related resources.
      items:
        required:
        - href
        - rel
        type: object
        properties:
          rel:
            type: array
            description: The short name(s) of the relationship corresponding to the link.
            items:
              type: string
          title:
            type: string
            description: A human-readable description of the link relationship.
          href:
            type: string
            description: The URL to a related resource.
            format: uri
          method:
            type: string
            description: The HTTP method to use to access this link.
            enum:
            - GET
            - POST
            - PUT
            - DELETE
          submissionMediaType:
            type: string
            description: The media type of the resource request.
          targetMediaType:
            type: string
            description: The media type of the resource response.
          description:
            type: string
            description: A human-readable description of the link relationship.
          publishDate:
            type: string
            format: date-time
            description: The date and time the file was published. The date and time will be returned in UTC (Zulu) format.
            example: '2026-05-28T19:42:28Z'
        additionalProperties: false
    ErrorMessage_2:
      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
          description: The high-level error that has occurred as indicated by the status code.
      additionalProperties: true
      description: Standard error message response.
    Links_2:
      title: Hypermedia Links
      description: Hypermedia links to related resources.
      type: array
      items:
        type: object
        required:
        - rel
        - href
        properties:
          rel:
            description: The short name(s) of the relationship corresponding to the link.
            type: array
            items:
              type: string
          title:
            description: A human-readable title of the link relationship.
            type: string
          description:
            description: A human-readable description of the link relationship.
            type: string
          href:
            description: The URL to a related resource.
            type: string
            format: uri
          method:
            type: string
            description: The HTTP method to use to access this link.
            enum:
            - GET
            - POST
            - PUT
            - DELETE
          submissionMediaType:
            description: The media type of the resource request.
            type: string
          targetMediaType:
            description: The media type of the resource response.
            type: string
          publishDate:
            description: The date and time the file was published.  The date and time will be returned in UTC (Zulu) format.
            example: '2025-04-24T19:42:28Z'
            type: string
            format: date-time
        additionalProperties: false
  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:
            locations: read location resources
        authorizationCode:
          authorizationUrl: /oauth2/v3/authorize
          tokenUrl: /oauth2/v3/token
          scopes:
            locations: read location resources
x-refined-from:
- usps-locations-openapi.yml
- usps-locations-openapi.yml
- usps-service-standards-files-openapi.yml
x-provenance:
  method: harvested
  publisher: United States Postal Service
  source: https://developers.usps.com/sites/default/files/apidoc_specs/locations_20.yaml
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)