swagger.yaml

swagger: "2.0"
info:
  version: 1.0.0
  title: locache
  description: 
    A simple service to provide geolocal/temporal information.
    Currently chains together google maps' geolocation and timezone APIs
    so you don't have to sign up for a token. This means that you really can't
    spam this service, or we both run out of free API calls and that's no fun
    for anyone...
  termsOfService: "You will not spam this service."
  contact:
    email: steven@gnobel.com
  license:
    name: MIT
    url: http://github.com/gruntjs/grunt/blob/master/LICENSE-MIT
host: locache.herokuapp.com
basePath: /
schemes:
  - http
consumes:
  - application/json
produces:
  - application/json
paths:
  /:
    get:
      description: Retrieve geo and timezone information for a location
        of interest, at a particular time (for DST calculations).
      parameters:
        - name: location
          in: query
          type: string
          required: true
          description: location of interest.
        - name: timestamp
          in: query
          type: integer
          description: seconds from `00:00 01-01-1970 UTC`, in time local to
            `location`. If not provided, the timestamp of the GET request is used.
      responses:
        200:
          description: Look at the JSON Schema property descriptions.
          schema:
            required:
              - formattedAddress
              - city
              - country
              - timeUntilTomorrow
              - lng
              - lat
              - timeZoneId
              - s
              - utcFromTimestamp
              - dstOffset
              - utcOffset
              - rawOffset
              - timeZoneName
            properties:
              formattedAddress:
                type: string
                example: Prenzlauer Allee 227, 10405 Berlin, Germany
              city:
                type: string
                example: Berlin
              country:
                type: string
                example: Germany
              timeUntilTomorrow:
                type: integer
                description: seconds until 00:00, local time
                example: 19851
              lng:                
                type: number
                format: float
                description: approximate longitude
                example: 13.42027
              lat:
                type: number
                format: float
                description: approximate latitude
                example: 52.53334
              timeZoneId:
                type: string
                example: Europe/Berlin
              s:
                type: string
                description: state or province
                example: Berlin
              utcFromTimestamp: 
                type: string
                description: the UTC timestamp from which DST is inferred.
                  This is either the UTC timestamp when the other properties
                  were calculated, or the timestamp provided in the initial
                  GET request.
                example: "2016-03-28 16:29:09 UTC"
              dstOffset:
                type: integer
                description: at `utcFromTimestamp`, what is the current
                  daylight savings offset (from UTC). This is 0 if DST is
                  not locally in effect.
                example: 3600
              utcOffset:
                type: integer
                example: 7200
                description: how many seconds from UTC is the time zone,
                  factoring in daylight savings, at `utcFromTimestamp`?
              rawOffset:
                type: integer
                description: how many seconds from UTC is the time zone,
                  not factoring in daylight savings, at `utcFromTimestatmp`?
                example: 3600
              timeZoneName:
                type: string
                example: "CEST"