NAV
bash ruby python

Introduction

Welcome to the Surf Report API!

Surf Report is a RESTful API that returns hour-by-hour surfing conditions for a specific beach. Surfing conditions include the surf height, wind speed, tide levels, and water temperature. Surf Report also returns a general recommendation for whether to go surfing at the specified beach.

An up-to-date list of available beaches is at http://example.com/surfreport/beaches_available.

Surf Report uses OAuth 2 for authentication and supports responses in JSON.

Check out the code examples in the panel to the right. Use the tabs at the top of the panel to switch the programming language of the examples.

Get Started

Here are four steps to get started with Surf Report:

  1. Sign up for an account.

    Go to https://market.mashape.com/ and click the Sign Up button to sign up for an account.

  2. Get API keys.

    You need an API key to use Surf Report. Go to http://docs.mashape.com//api-keys to learn how to get your API key.

    We use API keys to:

    • Authenticate calls to Surf Report to registered users only.
    • Track who makes Surf Report requests.
    • Track how often people are using Surf Report.

  3. Make a request.

    The root domain for making requests is https://simple-weather.p.mashape.com/surfreport.

  4. Review available endpoints.

    The available endpoint is /surfreport/{beachID}.

    {beachID} is the ID for the specified beach. An up-to-date list of available beaches is at http://example.com/surfreport/beaches_available.

Authentication

To authorize, use this code:

require 'surfreport'
api = SurfReport::APIClient.authorize!('waveswaveswaves')
import surfreport
api = surfreport.authorize('waveswaveswaves')
# With shell, just pass the correct header with each request.
curl "api_endpoint_here"
  -H "Authorization: waveswaveswaves"

Replace waveswaveswaves with your API key.

You’ll need an API key to access the Surf Report API. Go to http://docs.mashape.com//api-keys to learn how to get your API key.

You must use OAuth 2 for authentication.

Include your API key in all API requests to the server in a header that looks like this:

Authorization: waveswaveswaves

Error Codes for Invalid Authentication

Error Code Description Message Displayed
401 Missing or invalid authentication credentials The authentication credentials are missing or invalid.
403 Missing or invalid authorization credentials The authorization credentials are missing or invalid.

Rate Limits

You can make up to 2000 authenticated requests per hour. If you make too many requests, you’ll receive error 429 (“You reached the rate limit. Please try again later.”).

You cannot make unauthenticated requests.

Endpoint: beachID

The {beachID} endpoint returns the surf height, wind speed, tide levels, water temperature, and general recommendation for whether to go surfing for a specified beach.

Sample Request

require 'surfreport'
api = SurfReport::APIClient.authorize!('waveswaveswaves')
api.surfreports.get
import surfreport
api = surfreport.authorize('waveswaveswaves')
api.surfreports.get()
curl "http://example.com/api/surfreports"
  -H "Authorization: waveswaveswaves"

This request returns JSON structured like this:

{
"surfreport": [
    {
        "beach": "Santa Cruz",
        "monday": {
            "1pm": {
                "tide": 5,
                "wind": 15,
                "watertemp": 80,
                "surfheight": 5,
                "recommendation": "Go surfing!"
            },
            "2pm": {
                "tide": -1,
                "wind": 1,
                "watertemp": 50,
                "surfheight": 3,
                "recommendation": "Surfing conditions are okay, but not great."
            },
            "3pm": {
                "tide": -1,
                "wind": 10,
                "watertemp": 65,
                "surfheight": 1,
                "recommendation": "It's not a good day for surfing."
            }
        }
    }
]
}
Item Description
beach The selected beach. See http://example.com/surfreport/beaches_available for a list of beaches.
{day} The selected day of the week for the surf conditions. Response returns a default of 3 days and a maximum of 7 days.
{day}/{time} The time for the surf conditions. If request includes time parameter, returns surf conditions only for the specified hour. If requests does not include time parameter, returns 3 days of surf conditions, listed by hour.
{day}/{time}/tide The tide level at the specified day and time. Negative numbers mean the tide is going out. Positive numbers mean the tide is coming in. A 0 means the tide is neither going out nor coming in.
{day}/{time}/wind The wind speed at the specified day and time. Returned in either kilometers per hour or knots, depending on the unit specified in the request.
{day}/{time}/watertemp The temperature of the water at the specified day and time. Returned in Fahrenheit or Celsius, depending on the unit specified in the request.
{day}/{time}/surfheight The wave height at the specified day and time. Returned in feet or centimeters, depending on the unit specified in the request.
{day}/{time}/recommendation General recommendation of whether to go surfing at the specified day and time. Three possible recommendations: 1. “Go surfing!”, 2. “Surfing conditions are OK, but not great.”, 3. “It’s not a good day for surfing.” Based on returned values of elements wind, watertemp, and surfheight, with each element scored according to how close it is to ideal for surfing at the specified day and time.

HTTP Method

GET http://example.com/surfreport/{beachId}

Parameters

Parameter Data Type Required Description
days integer No Default is 3. Max is 7.
units string No Either imperial or metric. Default is imperial. Imperial: feet, knots, Fahrenheit. Metric: centimeters, kilometers per hour, Celsius.
time integer No Format is unix (milliseconds since 1970). Time zone is UTC.

Error and Status Codes

For every request, Surf Report returns one of the HTTP error or status codes listed here.

Error Code Description Message Displayed
200 Successful request Your request was successful.
400 Invalid request or request cannot be processed Your request is invalid or cannot be processed. {Error message that explains more about the specific problem.}
401 Missing or invalid authentication credentials The authentication credentials are missing or invalid.
403 Missing or invalid authorization credentials The authorization credentials are missing or invalid.
404 Specified beach not found The beach ID you specified is not currently included in our list of available beaches. The up-to-date list of available beaches is at http://example.com/surfreport/beaches_available.
429 Reached rate limit You reached the rate limit. Please try again later.
500 Problem with server There is an internal problem with the server. Please notify the Surf Report development team.
503 Service unavailable Surf Report is down for maintenance. Please try again later.

Error and Status Code Format Example


{"errors":[{"message":"You reached the rate limit. Please try again later.","code":429}]}

Surf Report error and status codes are delivered in JSON format.

bash ruby python