openapi: 3.0.3
info:
  title: FAOSTAT Bulk Download Catalog Downloads API
  description: The FAOSTAT Bulk Download API enables retrieval of complete FAOSTAT datasets as compressed CSV archives. Users can browse the dataset catalog to discover available datasets for any FAOSTAT domain, along with last-updated dates and direct download URLs for the zipped CSV files. No authentication is required.
  version: 1.0.0
  contact:
    name: FAOSTAT Support
    email: faostat@fao.org
    url: https://www.fao.org/faostat/en/#data
  license:
    name: CC BY-NC-SA 3.0 IGO
    url: https://creativecommons.org/licenses/by-nc-sa/3.0/igo/
  termsOfService: https://www.fao.org/contact-us/terms/en/
servers:
- url: https://bulks-faostat.fao.org/production
  description: FAOSTAT Bulk Download Production Server
tags:
- name: Downloads
  description: Download complete domain datasets as ZIP archives
paths:
  /{filename}:
    get:
      tags:
      - Downloads
      operationId: downloadDataset
      summary: Download a bulk dataset ZIP file
      description: Downloads a complete FAOSTAT dataset as a compressed ZIP file containing one or more CSV files. Filenames are obtained from the catalog endpoint. Files may be several hundred megabytes for large domains.
      parameters:
      - name: filename
        in: path
        required: true
        description: ZIP filename as listed in the catalog (e.g. Production_Crops_Livestock_E_All_Data_NOFLAG.zip)
        schema:
          type: string
        example: Production_Crops_Livestock_E_All_Data_NOFLAG.zip
      responses:
        '200':
          description: ZIP archive containing CSV data files
          content:
            application/zip:
              schema:
                type: string
                format: binary
                description: Compressed ZIP file containing CSV data
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  responses:
    NotFound:
      description: Dataset file not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: Access denied
      content:
        application/xml:
          schema:
            type: string
            description: XML error from S3-compatible storage
  schemas:
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error message
        code:
          type: integer
          description: Error code
externalDocs:
  description: FAOSTAT Data Download Page
  url: https://www.fao.org/faostat/en/#data