Put it all together


Pull together the various parts you’ve worked on and bring them together to showcase the full example.

I chose to format mine in Markdown syntax in a text editor. Here’s my example.


Returns information about surfing conditions at a specific beach ID, including the surf height, water temperature, wind, and tide. Also provides an overall recommendation about whether to go surfing.

{beachId} refers to the ID for the beach you want to look up. All Beach ID codes are available from our site.

Endpoint definition


HTTP method



Parameter Description Data Type
days Optional. The number of days to include in the response. Default is 3. integer
units Optional. Whether to return the values in imperial or metric measurements. Imperial will use feet, knots, and fahrenheit. Metric will use centimeters, kilometers per hour, and celsius. string
time Optional. If you include the time, then only the current hour will be returned in the response. integer. Unix format (ms since 1970) in UTC.

Sample request

curl --get --include 'https://simple-weather.p.mashape.com/surfreport/123?units=imperial&days=1&time=1433772000' -H 'X-Mashape-Key: EF3g83pKnzmshgoksF83V6JB6QyTp1cGrrdjsnczTkkYgYrp8p' -H 'Accept: application/json'

Sample response

    "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, not great."
                "3pm": {
                    "tide": -1,
                    "wind": 10,
                    "watertemp": 65,
                    "surfheight": 1,
                    "recommendation": "Not a good day for surfing."

The following table describes each item in the response.

{day}/{time}/surfheight : The height of the waves, returned in either feet or centimeters depending on the units you specify. A surf height of 3 feet is the minimum size needed for surfing. If the surf height exceeds 10 feet, it is not safe to surf. {day}/{time}/recommendation : An overall recommendation based on a combination of the various factors (wind, watertemp, surfheight). Three responses are possible: (1) "Go surfing!", (2) "Surfing conditions are okay, not great", and (3) "Not a good day for surfing." Each of the three factors is scored with a maximum of 33.33 points, depending on the ideal for each element. The three elements are combined to form a percentage. 0% to 59% yields response 3, 60% - 80% and below yields response 2, and 81% to 100% yields response 3.

Error and status codes

The following table lists the status and error codes related to this request.

Status code Meaning
605 Invalid time parameters. All time parameters must be in Java epoch format.
4112 The beach ID was not found in the lookup.

Code example

Code example

The following code samples shows how to use the surfreport endpoint to get the surf height for a specific beach.

<!DOCTYPE html>
<script src="http://code.jquery.com/jquery-2.1.1.min.js"></script>
var settings = {
  "async": true,
  "crossDomain": true,
  "dataType": "json",
  "url": "https://simple-weather.p.mashape.com/surfreport/25?days=1&units=metric",
  "method": "GET",
  "headers": {
    "accept": "application/json",
    "x-mashape-key": "APIKEY"

$.ajax(settings).done(function (response) {
<h2>Surf Height</h2>
<div id="surfheight"></div>

In this example, the ajax method from jQuery is used because it allows us to load a remote resource asynchronously.

In the request, you submit the authorization through the header rather than directly in the endpoint path. The endpoint limits the days returned to 1 in order to increase the download speed.

For demonstration purposes, the response is assigned to the response argument of the done method, and then written out to the surfheight tag on the page.

We're just getting the surf height, but there's a lot of other data you could choose to display.

Structure and templates

If you have a lot of endpoints to document, you’ll probably want to create templates that follow a common structure.

Additionally, if you want to add a lot of styling to each of the elements, you may want to push each of these elements into your template by way of a script. I’ll talk more about publishing in the upcoming sections, Publishing API Documentation.

Contributing back

If you would like to contribute back and encourage more available content and resources, you can click the Donate button below and contribute any amount.

Get new posts delivered straight to your inbox.

Subscriber count: 4,285