ENDPOINTS.md

API Endpoints

Find below a list of the different served endpoints and their parameters and responses. All API Endpooints only take parameters as query parameters!

All API endpoints deploy ratelimiting, you may only request data from the entire application 50 times within one minute. This ratelimit covers all endpoints at once rather than individually.

Weather Cards

Responds with a pre-rendered weather card otherwise JSON

Endpoint: /v1/card

Parameter	Type	Example
Location	String	Ilkeston, UK

Successful Response

Unsuccessful Response

{
   "statusCode": 404,
   "error": "Not Found",
   "message": "Location not found."
}

Weather

Responds with a weather information retrieved and cached from OpenWeatherMap The data is cached for 5 minutes

Endpoint: /v1/weather

Parameter	Type	Example
Location	String	Ilkeston, UK

Successful Response

{
   "coord":{
      "lon":-1.31,
      "lat":52.97
   },
   "weather":[
      {
         "id":803,
         "main":"Clouds",
         "description":"broken clouds",
         "icon":"04n"
      }
   ],
   "base":"stations",
   "main":{
      "temp":287.15,
      "pressure":1018,
      "humidity":87,
      "temp_min":287.15,
      "temp_max":287.15
   },
   "visibility":10000,
   "wind":{
      "speed":9.3,
      "deg":280
   },
   "clouds":{
      "all":75
   },
   "dt":1509227400,
   "sys":{
      "type":1,
      "id":5106,
      "message":0.0053,
      "country":"GB",
      "sunrise":1509173834,
      "sunset":1509208787
   },
   "id":2646274,
   "name":"Ilkeston",
   "cod":200
}

Unsuccessful Response

{
   "statusCode": 404,
   "error": "Not Found",
   "message": "Location not found."
}

Timezone

Responds with timezone information about a certain location. Data is retrieved and cached from Google Maps Timezone API The data is cached for 1 hour

Endpoint: /v1/timezone

Parameter	Type	Example
Longitute	Number	-1.31
Latitude	Number	52.97

Validation: The Longitute and Latitude paramters must fall within a specific range to be accepted. The ranges are -180/180 and 0/90 respectively.

Successful Response

{
   "dstOffset": 3600,
   "rawOffset": 0,
   "status": "OK",
   "timeZoneId": "Europe/London",
   "timeZoneName": "British Summer Time"
}

Unsuccessful Response

{
   "statusCode": 422,
   "error": "Unprocessable Entity",
   "message": "Invalid Location"
}

Moon Phase

Exposes information regarding the current phase for the specified location. The data is accurate within 1 second and is generated by SunCalc The data is cached for 1 second

Endpoint: /v1/timezone

Parameter	Type	Example
Longitute	Number	-1.31
Latitude	Number	52.97

Validation: The Longitute and Latitude paramters must fall within a specific range to be accepted. The ranges are -180/180 and 0/90 respectively.

Successful Response

{
   "fraction": 0.6052445878239309,
   "phase": 0.2837528353318091,
   "angle": -1.8807461325063894,
   "phaseName": "Waxing Gibbous"
}

Unsuccessful Response

{
   "statusCode": 422,
   "error": "Unprocessable Entity",
   "message": "Invalid Location"
}