openapi.yaml

openapi: 3.0.0
info:
  title: MaxMind GeoIPUpdate Protocol
  description: MaxMind GeoIPUpdate Protocol Design
  version: 1.0.0
  termsOfService: https://www.maxmind.com/en/end-user-license-agreement
  contact:
    name: MaxMind
    url: https://www.maxmind.com/en/company/contact-us
  license:
    name: MIT
    url: https://github.com/maxmind/geoipupdate/blob/main/LICENSE-MIT
paths:
  /geoip/databases/{edition-id}/update:
    servers:
      - url: https://updates.maxmind.com
        description: Official Update Server
    get:
      description: Get latest version
      operationId: latest
      security:
        - authentication: [ ]
      parameters:
        - name: edition-id
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/EditionID"
        - name: User-Agent
          in: header
          schema:
            type: string
            example: geoipupdate/6.0.0
            description: User Agent
        - name: db_md5
          in: query
          required: true
          schema:
            type: string
            example: "00000000000000000000000000000000"
            description: Local Database MD5 Summed
      responses:
        200:
          description: OK (gzipped)
          headers:
            Content-Encoding:
              schema:
                type: string
                example: gzip
            X-Database-Md5:
              schema:
                type: string
                example: "00000000000000000000000000000000"
                description: Uncompressed MD5 Hash, use hexadecimal encoded
            Last-Modified:
              schema:
                $ref: "#/components/schemas/RFC1123"
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        304:
          description: Unmodified
          content:
            text/plain:
              schema:
                type: string
        401:
          $ref: "#/components/responses/InvalidLicenseKey"
        404:
          $ref: "#/components/responses/NotFound"
        default:
          description: Download first 256 bytes on error message
          content:
            text/plain:
              schema:
                type: string
  /app/geoip_download:
    description: Permanent download link
    servers:
      - url: https://download.maxmind.com
        description: Official Download Server
    get:
      operationId: download
      security:
        - licenseKey: [ ]
      parameters:
        - $ref: "#/components/parameters/EditionID"
        - $ref: "#/components/parameters/Date"
        - $ref: "#/components/parameters/Suffix"
      responses:
        200:
          $ref: "#/components/responses/DownloadFile"
        400:
          $ref: "#/components/responses/InvalidParams"
        401:
          $ref: "#/components/responses/InvalidLicenseKey"
        404:
          $ref: "#/components/responses/NotFound"
  /app/geoip_download_by_token:
    description: Temporary download link
    servers:
      - url: https://download.maxmind.com
        description: Official Download Server
    get:
      operationId: downloadByToken
      security:
        - token: [ ]
      parameters:
        - $ref: "#/components/parameters/EditionID"
        - $ref: "#/components/parameters/Date"
        - $ref: "#/components/parameters/Suffix"
      responses:
        200:
          $ref: "#/components/responses/DownloadFile"
        400:
          $ref: "#/components/responses/InvalidParams"
        401:
          $ref: "#/components/responses/InvalidLicenseKey"
        404:
          $ref: "#/components/responses/NotFound"
components:
  parameters:
    EditionID:
      name: edition_id
      in: query
      required: true
      schema:
        $ref: "#/components/schemas/EditionID"
    Date:
      name: date
      in: query
      required: true
      schema:
        $ref: "#/components/schemas/Date"
    Suffix:
      name: suffix
      in: query
      required: true
      schema:
        $ref: "#/components/schemas/Suffix"
  responses:
    DownloadFile:
      description: OK
      headers:
        Content-Disposition:
          schema:
            type: string
          example: attachment; filename={edition-id}_{yyyyMMdd}.{suffix}
        Last-Modified:
          schema:
            $ref: "#/components/schemas/RFC1123"
        Etag:
          schema:
            type: string
            description: Quoted MD5 Hash Hex String
      content:
        application/zip:
          schema:
            type: string
            format: binary
            description: Only suffix "zip"
        application/gzip:
          schema:
            type: string
            format: binary
            description: Only suffix "tar.gz"
        text/plain:
          schema:
            type: string
            format: binary
            description: Only suffix "zip.sha256" or "tar.gz.sha256"
    InvalidParams:
      description: Invalid edition-id, date or suffix
      content:
        text/plain:
          schema:
            type: string
    InvalidLicenseKey:
      description: Invalid license key
      content:
        text/plain:
          schema:
            type: string
    NotFound:
      description: Database edition not found
      content:
        text/plain:
          schema:
            type: string
  schemas:
    EditionID:
      type: string
      description: Edition ID
      default: GeoLite2-Country
      enum:
        - GeoLite2-Country
        - GeoLite2-Country-ASN
        - GeoLite2-ASN
        - GeoLite2-ASN-CSV
        - GeoLite2-City
        - GeoLite2-City-CSV
    Date:
      type: string
      format: date
      example: 20230906
      description: Date (yyyyMMdd)
    Suffix:
      type: string
      default: zip
      enum:
        - zip
        - zip.sha256
        - tar.gz
        - tar.gz.sha256
      description: File Suffix Name
    RFC1123:
      type: string
      example: Wed, 01 Sep 2023 00:00:00 GMT
      description: RFC1123 format
  securitySchemes:
    token:
      type: apiKey
      name: token
      in: query
      description: Access Token
    licenseKey:
      type: apiKey
      name: license_key
      in: query
      description: License Key
    authentication:
      type: http
      scheme: basic
      description: Username as Account ID, Password as License Key