openapi: 3.0.0
servers:
  - description: SwaggerHub API Auto Mocking
    url: https://virtserver.swaggerhub.com/pcraig3/groundhog-day-api/1.2.1
  - description: ""
    url: https://groundhog-day.com
info:
  contact:
    email: hello@groundhog-day.com
    name: Paul Craig
    url: https://groundhog-day.com/api
  description: This API returns all of North America’s prognosticating animals and their yearly weather predictions.
  license:
    name: MIT
  title: Groundhog Day API
  version: 1.2.1
  x-logo:
    url: https://groundhog-day.com/apple-touch-icon.png
  x-origin:
    - format: openapi
      url: https://api.swaggerhub.com/apis/pcraig3/groundhog-day-api/1.2.1
      version: "3.0"
  x-providerName: groundhog-day.com
tags:
  - name: info
  - name: groundhogs
  - name: predictions
paths:
  /api/v1:
    get:
      description: Returns a welcome message.
      operationId: root
      responses:
        "200":
          content:
            application/json:
              examples:
                /:
                  value:
                    _links:
                      groundhog:
                        href: https://groundhog-day.com/api/v1/groundhogs/wiarton-willie
                      groundhogs:
                        href: https://groundhog-day.com/api/v1/groundhogs
                      predictions:
                        href: https://groundhog-day.com/api/v1/predictions?year=2022
                      self:
                        href: https://groundhog-day.com/api/v1/
                      spec:
                        href: https://groundhog-day.com/api/v1/spec
                    message: "Hello! Welcome to the Groundhog Day API: the leading Groundhog Day data source"
              schema:
                properties:
                  _links:
                    properties:
                      groundhog:
                        properties:
                          href:
                            type: string
                        required:
                          - href
                        type: object
                      groundhogs:
                        properties:
                          href:
                            type: string
                        required:
                          - href
                        type: object
                      predictions:
                        properties:
                          href:
                            type: string
                        required:
                          - href
                        type: object
                      self:
                        properties:
                          href:
                            type: string
                        required:
                          - href
                        type: object
                      spec:
                        properties:
                          href:
                            type: string
                        required:
                          - href
                        type: object
                    type: object
                  message:
                    type: string
                required:
                  - message
                type: object
                x-examples:
                  example-1:
                    _links:
                      groundhog:
                        href: https://groundhog-day.com/api/v1/groundhogs/wiarton-willie
                      groundhogs:
                        href: https://groundhog-day.com/api/v1/groundhogs
                      predictions:
                        href: https://groundhog-day.com/api/v1/predictions?year=2022
                      self:
                        href: https://groundhog-day.com/api/v1/
                      spec:
                        href: https://groundhog-day.com/api/v1/spec
                    message: "Hello! Welcome to the Groundhog Day API: the leading Groundhog Day data source"
          description: OK
      summary: Root
      tags:
        - info
  /api/v1/groundhogs:
    get:
      description: Returns all prognosticating animals with their known predictions.
      operationId: groundhogs
      parameters:
        - description: Filter groundhogs by country of origin (USA or Canada).
          in: query
          name: country
          schema:
            example: Canada or USA
            type: string
        - description: Filter groundhogs by type (actual, alive groundhogs, or other prognosticators)
          in: query
          name: isGroundhog
          schema:
            enum:
              - "1"
              - "0"
              - "true"
              - "false"
            type: string
      responses:
        "200":
          content:
            application/json:
              examples:
                /groundhogs:
                  value:
                    groundhogs:
                      - active: 1
                        city: Punxsutawney
                        contact: ""
                        coordinates: 40.9311988,-78.9622483
                        country: USA
                        currentPrediction: https://www.groundhog.org/prognostication
                        description: Punxsutawney Phil is a superstar prognosticating groundhog from Punxsutawney, Pennsylvania. He makes his predictions from his burrow on Gobler’s Knob. According to legend, Phil has made weather prognostications since 1886, owing his improbably long life to the miraculous “groundhog nog” administered at the annual Groundhog Picnic.
                        id: 1
                        image: https://groundhog-day.com/images/ghogs/punxsutawney-phil.png
                        isGroundhog: 1
                        name: Punxsutawney Phil
                        predictions:
                          - details: At 7:25 a.m. with 18,000 Phil Phans present, Phil saw his shadow! Six More Weeks of Winter!
                            shadow: 1
                            year: 2018
                          - details: NO Shadow at 7:28 AM; 14º fog & mist with -1º Wind Chill.
                            shadow: 0
                            year: 2019
                          - details: NO Shadow at 7:26 AM; 30º with light snow falling.
                            shadow: 0
                            year: 2020
                          - details: Shadow at 7:25 AM; 19º with light snow. Coronavirus fear prohibits crowds on Gobbler’s Knob.
                            shadow: 1
                            year: 2021
                          - details: Shadow at 7:27 AM; 27º with clear skies. A loyal crowd of thousands returned to Gobbler’s Knob.
                            shadow: 1
                            year: 2022
                        predictionsCount: 127
                        region: Pennsylvania
                        shortname: Phil
                        slug: punxsutawney-phil
                        source: https://www.groundhog.org/history-past-predictions
                        type: Groundhog
                      - active: 1
                        city: Barrington
                        contact: ""
                        coordinates: 43.5623505,-65.5700017
                        country: Canada
                        currentPrediction: https://twitter.com/CailinONeil/status/1488894511107485702
                        description: Lucy the Lobster makes Groundhog Day predictions on February 2nd to kick off the Lobster Crawl festival in Barrington, Nova Scotia. The Municipality of Barrington says Lucy is the only prognosticating crustacean to make a prediction in Canada. Bill Murray was reported as being bemused by the idea of a lobster forecaster.
                        id: 51
                        image: https://groundhog-day.com/images/ghogs/lucy-the-lobster.png
                        isGroundhog: 0
                        name: Lucy the Lobster
                        predictions:
                          - details: ""
                            shadow: 0
                            year: 2018
                          - details: ""
                            shadow: 1
                            year: 2019
                          - details: ""
                            shadow: 1
                            year: 2020
                          - details: ""
                            shadow: null
                            year: 2021
                          - details: ""
                            shadow: 1
                            year: 2022
                        predictionsCount: 4
                        region: Nova Scotia
                        shortname: Lucy
                        slug: lucy-the-lobster
                        source: https://twitter.com/lucylobsterns
                        type: Atlantic lobster
              schema:
                properties:
                  groundhogs:
                    items:
                      $ref: "#/components/schemas/Groundhog"
                    type: array
                type: object
                x-examples:
                  example-1:
                    - active: 1
                      city: Punxsutawney
                      contact: ""
                      country: USA
                      currentPrediction: https://www.groundhog.org/prognostication
                      description: Punxsutawney Phil is a superstar prognosticating groundhog from Punxsutawney, Pennsylvania. He makes his predictions from his burrow on Gobler’s Knob. According to legend, Phil has made weather prognostications since 1886, owing his improbably long life to the miraculous “groundhog nog” administered at the annual Groundhog Picnic.
                      id: 1
                      image: https://groundhog-day.com/images/ghogs/punxsutawney-phil.png
                      isGroundhog: 1
                      name: Punxsutawney Phil
                      predictions:
                        - details: No Shadow- Early Spring It was 28° at Gobbler’s Knob. Phil made his perdition of an Early Spring at 7:25 a.m.
                          shadow: 0
                          year: 2016
                        - details: 7:25 a.m. Saw His Shadow, Six More Weeks of Winter! There were a few snow flurries during the prognostication.
                          shadow: 1
                          year: 2017
                        - details: At 7:25 a.m. with 18,000 Phil Phans present, Phil saw his shadow! Six More Weeks of Winter!
                          shadow: 1
                          year: 2018
                        - details: NO Shadow at 7:28 AM; 14º fog & mist with -1º Wind Chill.
                          shadow: 0
                          year: 2019
                        - details: NO Shadow at 7:26 AM; 30º with light snow falling.
                          shadow: 0
                          year: 2020
                        - details: Shadow at 7:25 AM; 19º with light snow. Coronavirus fear prohibits crowds on Gobbler’s Knob.
                          shadow: 1
                          year: 2021
                        - details: Shadow at 7:27 AM; 27º with clear skies. A loyal crowd of thousands returned to Gobbler’s Knob.
                          shadow: 1
                          year: 2022
                      predictionsCount: 7
                      region: Pennsylvania
                      shortname: Phil
                      slug: punxsutawney-phil
                      source: https://www.groundhog.org/history-past-predictions
                      type: Groundhog
                    - active: 1
                      city: Barrington
                      contact: ""
                      country: Canada
                      currentPrediction: https://twitter.com/CailinONeil/status/1488894511107485702
                      description: Lucy the Lobster makes Groundhog Day predictions on February 2nd to kick off the Lobster Crawl festival in Barrington, Nova Scotia. The Municipality of Barrington says Lucy is the only prognosticating crustacean to make a prediction in Canada. Bill Murray was reported as being bemused by the idea of a lobster forecaster.
                      id: 46
                      image: https://groundhog-day.com/images/ghogs/lucy-the-lobster.png
                      isGroundhog: 0
                      name: Lucy the Lobster
                      predictions:
                        - details: ""
                          shadow: 0
                          year: 2018
                        - details: ""
                          shadow: 1
                          year: 2019
                        - details: ""
                          shadow: 1
                          year: 2020
                        - details: ""
                          shadow: null
                          year: 2021
                        - details: ""
                          shadow: 1
                          year: 2022
                      predictionsCount: 4
                      region: Nova Scotia
                      shortname: Lucy
                      slug: lucy-the-lobster
                      source: https://twitter.com/lucylobsterns
                      type: Atlantic lobster
          description: OK
      summary: Get all groundhogs
      tags:
        - groundhogs
  "/api/v1/groundhogs/{slug}":
    get:
      description: Returns a prognosticating animal and its known predictions.
      operationId: groundhog
      responses:
        "200":
          content:
            application/json:
              examples:
                /groundhogs/lucy-the-lobster:
                  value:
                    groundhog:
                      active: 1
                      city: Barrington
                      contact: ""
                      coordinates: 43.5623505,-65.5700017
                      country: Canada
                      currentPrediction: https://twitter.com/CailinONeil/status/1488894511107485702
                      description: Lucy the Lobster makes Groundhog Day predictions on February 2nd to kick off the Lobster Crawl festival in Barrington, Nova Scotia. The Municipality of Barrington says Lucy is the only prognosticating crustacean to make a prediction in Canada. Bill Murray was reported as being bemused by the idea of a lobster forecaster.
                      id: 51
                      image: https://groundhog-day.com/images/ghogs/lucy-the-lobster.png
                      isGroundhog: 0
                      name: Lucy the Lobster
                      predictions:
                        - details: ""
                          shadow: 0
                          year: 2018
                        - details: ""
                          shadow: 1
                          year: 2019
                        - details: ""
                          shadow: 1
                          year: 2020
                        - details: ""
                          shadow: null
                          year: 2021
                        - details: ""
                          shadow: 1
                          year: 2022
                      predictionsCount: 4
                      region: Nova Scotia
                      shortname: Lucy
                      slug: lucy-the-lobster
                      source: https://twitter.com/lucylobsterns
                      type: Atlantic lobster
              schema:
                properties:
                  groundhog:
                    $ref: "#/components/schemas/Groundhog"
                type: object
          description: OK
        "400":
          content:
            application/json:
              examples:
                /groundhogs/punxsutawney-paul:
                  value:
                    error:
                      message: "BadRequestError: Bad groundhog identifier ('punxsutawney-paul'), maybe you spelled it wrong?"
                      status: 400
                      timestamp: 2022-10-03T03:37:51.567Z
              schema:
                properties:
                  error:
                    properties:
                      message:
                        type: string
                      status:
                        type: integer
                      timestamp:
                        type: string
                    required:
                      - status
                      - message
                      - timestamp
                    type: object
                type: object
                x-examples:
                  example-1:
                    error:
                      message: "BadRequestError: Bad groundhog identifier ('fake'), maybe you spelled it wrong?"
                      status: 400
                      timestamp: 2022-10-03T03:36:54.661Z
          description: Bad Request
      summary: Get a groundhog by slug
      tags:
        - groundhogs
    parameters:
      - description: "Groundhog name in kebab-case: (eg, lucy-the-lobster)"
        in: path
        name: slug
        required: true
        schema:
          type: string
  /api/v1/predictions:
    get:
      description: Get all predictions for a given year.
      operationId: predictions
      parameters:
        - description: A calendar year
          in: query
          name: year
          schema:
            minimum: 1886
            type: integer
      responses:
        "200":
          content:
            application/json:
              examples:
                /predictions?year=2020:
                  value:
                    predictions:
                      - details: NO Shadow at 7:26 AM; 30º with light snow falling.
                        groundhog:
                          active: 1
                          city: Punxsutawney
                          contact: ""
                          coordinates: 40.9311988,-78.9622483
                          country: USA
                          currentPrediction: https://www.groundhog.org/prognostication
                          description: Punxsutawney Phil is a superstar prognosticating groundhog from Punxsutawney, Pennsylvania. He makes his predictions from his burrow on Gobler’s Knob. According to legend, Phil has made weather prognostications since 1886, owing his improbably long life to the miraculous “groundhog nog” administered at the annual Groundhog Picnic.
                          id: 1
                          image: https://groundhog-day.com/images/ghogs/punxsutawney-phil.png
                          isGroundhog: 1
                          name: Punxsutawney Phil
                          predictionsCount: 127
                          region: Pennsylvania
                          shortname: Phil
                          slug: punxsutawney-phil
                          source: https://www.groundhog.org/history-past-predictions
                          type: Groundhog
                        shadow: 0
                        year: 2020
                      - details: ""
                        groundhog:
                          active: 1
                          city: Barrington
                          contact: ""
                          coordinates: 43.5623505,-65.5700017
                          country: Canada
                          currentPrediction: https://twitter.com/CailinONeil/status/1488894511107485702
                          description: Lucy the Lobster makes Groundhog Day predictions on February 2nd to kick off the Lobster Crawl festival in Barrington, Nova Scotia. The Municipality of Barrington says Lucy is the only prognosticating crustacean to make a prediction in Canada. Bill Murray was reported as being bemused by the idea of a lobster forecaster.
                          id: 51
                          image: https://groundhog-day.com/images/ghogs/lucy-the-lobster.png
                          isGroundhog: 0
                          name: Lucy the Lobster
                          predictionsCount: 127
                          region: Nova Scotia
                          shortname: Lucy
                          slug: lucy-the-lobster
                          source: https://twitter.com/lucylobsterns
                          type: Atlantic lobster
                        shadow: 1
                        year: 2020
              schema:
                properties:
                  predictions:
                    items:
                      $ref: "#/components/schemas/Prediction"
                    type: array
                type: object
                x-examples:
                  example-1:
                    - details: NO Shadow at 7:26 AM; 30º with light snow falling.
                      groundhog:
                        active: 1
                        city: Punxsutawney
                        contact: ""
                        country: USA
                        currentPrediction: https://www.groundhog.org/prognostication
                        description: Punxsutawney Phil is a superstar prognosticating groundhog from Punxsutawney, Pennsylvania. He makes his predictions from his burrow on Gobler’s Knob. According to legend, Phil has made weather prognostications since 1886, owing his improbably long life to the miraculous “groundhog nog” administered at the annual Groundhog Picnic.
                        id: 1
                        image: https://groundhog-day.com/images/ghogs/punxsutawney-phil.png
                        isGroundhog: 1
                        name: Punxsutawney Phil
                        region: Pennsylvania
                        shortname: Phil
                        slug: punxsutawney-phil
                        source: https://www.groundhog.org/history-past-predictions
                        type: Groundhog
                      shadow: 0
                      year: 2020
                    - details: ""
                      groundhog:
                        active: 1
                        city: Barrington
                        contact: ""
                        country: Canada
                        currentPrediction: https://twitter.com/CailinONeil/status/1488894511107485702
                        description: Lucy the Lobster makes Groundhog Day predictions on February 2nd to kick off the Lobster Crawl festival in Barrington, Nova Scotia. The Municipality of Barrington says Lucy is the only prognosticating crustacean to make a prediction in Canada. Bill Murray was reported as being bemused by the idea of a lobster forecaster.
                        id: 46
                        image: https://groundhog-day.com/images/ghogs/lucy-the-lobster.png
                        isGroundhog: 0
                        name: Lucy the Lobster
                        region: Nova Scotia
                        shortname: Lucy
                        slug: lucy-the-lobster
                        source: https://twitter.com/lucylobsterns
                        type: Atlantic lobster
                      shadow: 1
                      year: 2020
          description: OK
        "302":
          description: Found
          headers:
            location:
              description: /api/v1/predictions?year=2022
              schema:
                type: string
        "400":
          content:
            application/json:
              examples:
                /predictions?year=1800:
                  value:
                    error:
                      message: "BadRequestError: The 'year' must be between 1886 and 2022 (inclusive)."
                      status: 400
                      timestamp: 2022-10-03T03:38:55.169Z
              schema:
                properties:
                  error:
                    properties:
                      message:
                        type: string
                      status:
                        type: integer
                      timestamp:
                        type: string
                    required:
                      - status
                      - message
                      - timestamp
                    type: object
                type: object
                x-examples:
                  example-1:
                    error:
                      message: "BadRequestError: The 'year' must be between 1886 and 2022 (inclusive)."
                      status: 400
                      timestamp: 2022-10-03T03:38:55.169Z
          description: Bad Request
      summary: Get predictions for a given year
      tags:
        - predictions
    parameters: []
  /api/v1/spec:
    get:
      description: Gets the schema for the JSON API as a yaml file.
      operationId: spec
      responses:
        "200":
          description: OK
          headers:
            content-disposition:
              description: attachment; filename="Groundhog-Day-API.v1.yaml"
              schema:
                type: string
            content-type:
              description: text/yaml; charset=UTF-8
              schema:
                type: string
      summary: Get JSON schema
      tags:
        - info
components:
  schemas:
    Groundhog:
      description: An animal that makes an annual prediction on Groundhog Day.
      properties:
        active:
          enum:
            - 0
            - 1
          exclusiveMaximum: false
          exclusiveMinimum: false
          maximum: 1
          minimum: 0
          type: integer
        city:
          type: string
        contact:
          type: string
        coordinates:
          type: string
        country:
          type: string
        currentPrediction:
          type: string
        description:
          type: string
        id:
          minimum: 1
          type: integer
        image:
          type: string
        isGroundhog:
          exclusiveMaximum: false
          exclusiveMinimum: false
          maximum: 1
          minimum: 0
          type: integer
        name:
          type: string
        predictions:
          items:
            $ref: "#/components/schemas/Prediction"
          type: array
        predictionsCount:
          description: All predictions, excluding nulls.
          minimum: 1
          type: integer
        region:
          type: string
        shortname:
          type: string
        slug:
          type: string
        source:
          type: string
        type:
          type: string
      required:
        - id
        - slug
        - shortname
        - name
        - city
        - region
        - country
        - coordinates
        - source
        - contact
        - currentPrediction
        - isGroundhog
        - type
        - active
        - description
        - image
      title: Groundhog
      type: object
      x-examples:
        /groundhog/lucy-the-lobster:
          groundhog:
            active: 1
            city: Barrington
            contact: ""
            coordinates: 43.5623505,-65.5700017
            country: Canada
            currentPrediction: https://twitter.com/CailinONeil/status/1488894511107485702
            description: Lucy the Lobster makes Groundhog Day predictions on February 2nd to kick off the Lobster Crawl festival in Barrington, Nova Scotia. The Municipality of Barrington says Lucy is the only prognosticating crustacean to make a prediction in Canada. Bill Murray was reported as being bemused by the idea of a lobster forecaster.
            id: 51
            image: https://groundhog-day.com/images/ghogs/lucy-the-lobster.png
            isGroundhog: 0
            name: Lucy the Lobster
            predictions:
              - details: ""
                shadow: 0
                year: 2018
              - details: ""
                shadow: 1
                year: 2019
              - details: ""
                shadow: 1
                year: 2020
              - details: ""
                shadow: null
                year: 2021
              - details: ""
                shadow: 1
                year: 2022
            region: Nova Scotia
            shortname: Lucy
            slug: lucy-the-lobster
            source: https://twitter.com/lucylobsterns
            type: Atlantic lobster
    Prediction:
      description: An annual prediction of an early spring or a longer winter.
      properties:
        details:
          type: string
        groundhog:
          $ref: "#/components/schemas/Groundhog"
        shadow:
          maximum: 1
          minimum: 0
          nullable: true
          type: integer
        year:
          exclusiveMinimum: false
          minimum: 1886
          type: integer
      required:
        - year
        - shadow
        - details
      title: Prediction
      type: object
      x-examples:
        /predictions?year=2022:
          details: ""
          groundhog:
            active: 1
            city: Barrington
            contact: ""
            coordinates: 43.5623505,-65.5700017
            country: Canada
            currentPrediction: https://twitter.com/CailinONeil/status/1488894511107485702
            description: Lucy the Lobster makes Groundhog Day predictions on February 2nd to kick off the Lobster Crawl festival in Barrington, Nova Scotia. The Municipality of Barrington says Lucy is the only prognosticating crustacean to make a prediction in Canada. Bill Murray was reported as being bemused by the idea of a lobster forecaster.
            id: 46
            image: https://groundhog-day.com/images/ghogs/lucy-the-lobster.png
            isGroundhog: 0
            name: Lucy the Lobster
            region: Nova Scotia
            shortname: Lucy
            slug: lucy-the-lobster
            source: https://twitter.com/lucylobsterns
            type: Atlantic lobster
          shadow: 1
          year: 2022
