NAV Navbar
Logo
shell javascript

Introduction

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [
          -77.8673,
          40.8043
        ]
      },
      "properties": {
        "type": "Sunset",
        "quality": "Poor",
        "quality_percent": 23.02,
        "quality_value": -253.673,
        "temperature": 19.53,
        "last_updated": "2018-05-29T18:00:00Z",
        "imported_at": "2018-05-29T23:14:27Z",
        "valid_at": "2018-05-31T00:36:00Z",
        "dusk": {
          "civil": "2018-05-31T01:08:00Z",
          "nautical": "2018-05-31T01:49:00Z",
          "astronomical": "2018-05-31T02:37:00Z"
        },
        "source": "NAM",
        "distance": 1.359
      }
    }
  ]
}

Sunburst is a RESTful Web API, used for fetching SunsetWx’s sunrise and sunset quality predictions.

Sunburst currently formats responses exclusively in JSON, with geographical data conforming to the GeoJSON spec.

Both commercial and non-commercial plans are available here. We only ask that you select a commercial plan if you or your organization directly or indirectly profit from using this service, and that you provide proper attribution back to SunsetWx for the use of our data.

For attribution, we prefer that you use an unmodified vector of our logomark, along with our name, both at legible sizes, and that they link back to our website SunsetWx.

If you enjoy our forecasts, every subscription helps to keep this service online.

API support is available via an email to:
team@sunsetwx.com


Customizing the Docs: URL Parameters

This API reference can be filled in using URL parameters for working copy-and-paste examples.

Parameter Description
email Email Address
reg_key Registration Key
token Access Token
session_id Session ID
session_key Session Key

Authorization

To use a token, place the keyword Bearer, followed by a space, with the access token from POST Login or POST Login Session, inside of a request’s Authorization HTTP header.

GET /v1/quality?type=sunset&geo=40.79,-77.86 HTTP/1.1
Authorization: Bearer TOKEN[6340beaa-7279-4055-a6ec-fc9422ee0ad8]

The API uses bearer access tokens for performing API calls/requests. Currently, tokens expire one week after their creation by default.

Access tokens are granted from a successful authorization, based on ether a traditional email and password pair, or a revokable client identifier and client secret session pair, compatible with OAuth 2.0 as client_credentials.

Revokable sessions are randomly-generated credentials that can be used in place of an email and password pair. Session pairs can be revoked individually or all at once by their login type.

Each access token and session pair contains a scope value that determines which resources a token may access. Scopes protect unsuspecting implementers from generating access tokens that could unsuspectingly reveal sensitive information or modify account settings. Scope values are space-delimited.

For example, a session with a scope value of all can create access tokens that contain any valid scope value, including all. A session with a scope value of predictions can only create access tokens with a scope value of predictions. A session with a scope value of predictions account can create access tokens with ether predictions, account, or predictions account. Use scope values containing account with caution, as they may reveal sensitive information or allow modifications to account settings.

Each access token and session pair may be optionally limited to an origin URL that is sent by web browsers during requests and contains the current site making a request. Glob-style selectors may be used. Additionally, access tokens and sessions may be optionally limited to an IP address or CIDR network. If a request does not match the given source requirements, the request will fail to help prevent the theft of credentials.

Login Types

Parameter Description
access Returns an access token. (default)
remember_me Returns a client identifier and client secret session pair. Stores up to 20 revokable sessions lasting one year. Once the limit is reached, the oldest session pair is silently erased.
permanent Returns a client identifier and client secret session pair. Stores up to 20 revokable sessions. Once the limit is reached, an error is returned.

Scopes

Value Description
predictions Grants access to forecasting endpoints, such as /v1/quality. (default)
account Grants permissions to access potentially sensitive account information and modify account settings. Use with caution.
all Grants all current and future scope permissions. Use with caution.

POST Login

Confirm that you can use the email address associated with your account by clicking the link that we send. Once your account has been activated, you may login by submitting your email and password.

curl -X "POST" "https://sunburst.sunsetwx.com/v1/login" \
  -u "EMAIL[email@example.com]:PASSWORD[Pr1ndl3a$85012]" \
  -d "grant_type=password"

# Generate a revokable session for logging in.
curl -X "POST" "https://sunburst.sunsetwx.com/v1/login" \
  -u "EMAIL[email@example.com]:PASSWORD[Pr1ndl3a$85012]" \
  -d "grant_type=password" \
  -d "type=remember_me"

try {
  const sunburst = new SunburstJS();

  const session = await sunburst.createSession({
    email: 'EMAIL[email@example.com]',
    password: 'PASSWORD[Pr1ndl3a$85012]',
    type: 'permanent',
    scope: ['predictions']
  });

  console.log(session);

} catch (ex) {
  // Handle general network or parsing errors.
  return console.error(ex);
}

If the request is successful, the API responds with the access token, the number of seconds until the access token expires, and a success message:

{
  "message": "Login successful",
  "notice": "If this token must be used directly by web browsers, which is not recommended, we suggest setting one or more space-delimited origins, using the origins parameter, to discourage token theft.",
  "access_token": "TOKEN[6340beaa-7279-4055-a6ec-fc9422ee0ad8]",
  "token_type": "Bearer",
  "expires_in": 604800,
  "scope": "predictions"
}

Revokable sessions can be used for authorization by setting the type request parameter to remember_me or permanent

{
  "message": "Login successful",
  "notice": "If this token must be used directly by web browsers, which is not recommended, we suggest setting one or more space-delimited origins, using the origins parameter, to discourage token theft.",
  "access_token": "TOKEN[6340beaa-7279-4055-a6ec-fc9422ee0ad8]",
  "token_type": "Bearer",
  "expires_in": 604800,
  "scope": "predictions",
  "session": {
    "client_id": "SESSION_ID[f78fe615-8eb1-48c4-be21-e5f4f437e8ba]",
    "client_secret": "SESSION_KEY[18qwl0htsPX|[!NGQ@[qK{X;[&^EVzaH]",
    "scope": "predictions"
  }
}

POST /v1/login authenticates a user against their stored authorization credentials and then returns a bearer access token if successful.

Parameters are accepted via an HTTP Basic authorization header or a POST form.

Request Body Parameters

Parameter Description
username ✔ A string that contains a valid email address to be used for account authentication. Required as a body parameter or as part of a Basic authentication header.
password ✔ A string that is longer than eight characters containing at least one uppercase character, one lowercase character, and one number. Required as a body parameter or as part of a Basic authentication header.
grant_type ✔ A string containing an OAuth 2.0 grant type of password. This parameter is required for OAuth 2.0 response formatting. Omitting this parameter returns a backwards-compatible proprietary response format.
passcode A string containing a TOTP passcode to authenticate with two-factor authentication, required if enabled.
type A string containing a valid login type. Default: access
scope A string containing a space-separated list of valid scopes that determine the permissions of the returned token. Default: predictions
origins A string containing a space-separated list of website URLs that are allowed to use the returned token. Accepts Glob-like syntax.
addresses A string containing a space-separated list of IPs and CIDR networks that are allowed to use the returned token.
expires_in A string containing a duration, in seconds, until the returned token expires. This value does not apply to sessions. Default: 604800, Min: 900, Max: 604800.

✔ == Required Parameter

Response Parameters

Parameter Description
message A string that contains a status message related to the request.
notice A string that contains one or more usage recommendations for developers using the API.
token_type A string containing the token type, which will always be Bearer.
access_token A string that contains a Bearer authorization token.
scope A string containing a space-separated list of space-separated list of valid scopes that determine the permissions of the returned token.
origins A string containing a space-separated list of website URLs that are allowed to use the returned token. Accepts Glob-like syntax.
addresses A string containing a space-separated list of IPs and CIDR networks that are allowed to use the returned token.
expires_in An integer representing the number of seconds from the time of the response, until the token expires. This value does not apply to sessions.
session An object containing populated client_id and client_secret string fields, representing a revokable session pair.


POST Login Session

Using a revokable session pair, explained in the previous section, you can login using this endpoint.

curl -X "POST" "https://sunburst.sunsetwx.com/v1/login/session" \
  -u "SESSION_ID[f78fe615-8eb1-48c4-be21-e5f4f437e8ba]:SESSION_KEY[18qwl0htsPX|[!NGQ@[qK{X;[&^EVzaH]" \
  -d "grant_type=client_credentials"

let sunburst = new SunburstJS({
  clientId: 'SESSION_ID[f78fe615-8eb1-48c4-be21-e5f4f437e8ba]',
  clientSecret: 'SESSION_KEY[18qwl0htsPX|[!NGQ@[qK{X;[&^EVzaH]',
  scope: ['predictions']
});

If the request is successful, the API responds with the access token, the number of seconds until the access token expires, and a success message:

{
  "message": "Login successful",
  "notice": "If this token must be used directly by web browsers, which is not recommended, we suggest setting one or more space-delimited origins, using the origins parameter, to discourage token theft.",
  "access_token": "TOKEN[6340beaa-7279-4055-a6ec-fc9422ee0ad8]",
  "token_type": "Bearer",
  "expires_in": 604800,
  "scope": "predictions"
}

POST /v1/login/session authenticates a user against stored session credentials and then returns a bearer access token if successful.

Parameters are accepted via an HTTP Basic authorization header or a POST form.

Request Body Parameters

Parameter Description
client_id ✔ A string that contains a valid session ID to be used for account authentication. Required as a body parameter or as part of a Basic authentication header.
client_secret ✔ A string that contains a valid session key to be used for account authentication. Required as a body parameter or as part of a Basic authentication header.
grant_type ✔ A string containing an OAuth 2.0 grant type of client_credentials.
scope A string containing a space-separated list of valid scopes that determine the permissions of the returned token. Default: The session scope.
origins A string containing a space-separated list of website URLs that are allowed to use the returned token. Accepts Glob-like syntax.
addresses A string containing a space-separated list of IPs and CIDR networks that are allowed to use the returned token.
expires_in A string containing a duration, in seconds, until the returned token expires. This value does not apply to sessions. Default: 604800, Min: 900, Max: 604800.

✔ == Required Parameter

Response Parameters

Parameter Description
message A string that contains a status message related to the request.
notice A string that contains one or more usage recommendations for developers using the API.
token_type A string containing the token type, which will always be Bearer.
access_token A string that contains a Bearer authorization token.
scope A string containing a space-separated list of space-separated list of valid scopes that determine the permissions of the returned token.
origins A string containing a space-separated list of website URLs that are allowed to use the returned token. Accepts Glob-like syntax.
addresses A string containing a space-separated list of IPs and CIDR networks that are allowed to use the returned token.
expires_in An integer representing the number of seconds from the time of the response, until the token expires. This value does not apply to sessions.


POST Logout

curl -X "POST" "https://sunburst.sunsetwx.com/v1/logout" \
  -h "Authorization: Bearer TOKEN[6340beaa-7279-4055-a6ec-fc9422ee0ad8]"

try {
  const resp = await sunburst.logout();
  console.log(resp);
} catch (ex) {
  return console.error(ex);
}

{
  "message": "Logged out"
}

Required Scope: account

POST /v1/logout invalidates a valid token. The logout request is then synced to all nodes in our cluster.

Parameter Description
message A string that contains a status message related to the request.


Predictions

Quality Descriptions

Quality (%) Description
Poor
(0-25%)		 Little to no color, with precipitation or a thick cloud layer often blocking a direct view of the sun.
Fair
(25-50%)		 Some color for a short time, with conditions ranging from mostly cloudy, or hazy, to clear, with little to no clouds at all levels.
Good
(50-75%)		 A fair amount of color, often multi-colored, lasting a considerable amount of time. Often caused by scattered clouds at multiple levels.
Great
(75-100%)		 Extremely vibrant color lasting 30 minutes or more. Often caused by multiple arrangements of clouds at multiple levels, transitioning through multiple stages of vivid color.

Quality Percent

quality_percent provides a simple and familiar way of understanding the meaning of quality_value, meant specifically as a reference for an audience of people rather than for scientific reference.

Quality Value


Sunrise

Quality (%) Range
Poor (< 25%) -771 to -224
Fair (< 50%) -223 to -113.4
Good (< 75%) -113.4 to 105.8
Great (<= 100%) 105.8 to 325


Sunset

Quality (%) Range
Poor (< 25%) -650 to -219.5
Fair (< 50%) -219.5 to -76
Good (< 75%) -76 to 67.49
Great (<= 100%) 67.49 to 211

Last Updated

This property is used to identify which model the specific prediction was generated from and its age.

Dawn

The dawn property is always returned with Sunrise forecast results. It contains twilight times for the location and event type.

Dusk

The dusk property is always returned with Sunset forecast results. It contains twilight times for the location and event type.

Sorting Methods

Ascending Descending
distance_asc distance_desc
quality_asc quality_desc
valid_at_asc valid_at_desc
last_updated_asc last_updated_desc
temperature_asc temperature_desc

GET Quality

curl "https://sunburst.sunsetwx.com/v1/quality" \
  -d "geo=40.7933949,-77.8600012" \
  -H "Authorization: Bearer TOKEN[6340beaa-7279-4055-a6ec-fc9422ee0ad8]" \
  -G

try {
  const resp = await sunburst.quality({
    geo: [40.7933949, -77.8600012]
  });
  features.forEach(({ geometry, properties }) => {
    const { coordinates } = geometry;
    console.log({ coordinates, properties });
  });
} catch (ex) {
  // Handle general network or parsing errors.
  return console.error(ex);
}

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [
          -77.8673,
          40.8043
        ]
      },
      "properties": {
        "type": "Sunrise",
        "quality": "Poor",
        "quality_percent": 21.04,
        "quality_value": -327.115,
        "temperature": 22.07,
        "last_updated": "2018-07-02T00:00:00Z",
        "imported_at": "2018-07-02T02:54:53Z",
        "dawn": {
          "astronomical": "2018-07-02T07:39:00Z",
          "nautical": "2018-07-02T08:29:00Z",
          "civil": "2018-07-02T09:11:00Z"
        },
        "valid_at": "2018-07-02T09:44:00Z",
        "source": "NAM",
        "distance": 1.359
      }
    }
  ]
}

Required Scope: predictions

GET /v1/quality returns an array of points, within range of the given coordinates, that contains quality predictions for the next sunrise or sunset.

Request URL Search Parameters

Parameter Description
geo ✔ A string that contains a valid latitude and longitude point, with latitude and longitude values separated by a comma. geo should be a valid RFC5870-formatted geo URI, excluding its scheme which is geo.
type A string that contains a valid model type: sunrise or sunset. Default: Use the next-occurring event type.
source A string that contains a valid model source: GFS or NAM.
Default: Use the highest-resolution model that is available.
radius A float or double that limits the amount of returned model points by the given distance in kilometers.
Default:
NAM: 8.04672km
GFS: 32.18688km
Min: 0km
Max: 321.8688km
limit An integer that limits the number of returned model points.
Default: 200000000
Min: 1
Max: 200000000
sort A string that contains a valid result sorting method, listed above.
Default: distance_asc
after A string containing an RFC3339/ISO8601-formatted timestamp value that the events in the result should occur after. This is used to view forecasts up to four days into the future and one day into the past. Defaults to the current time.

✔ == Required Parameter

Response Parameters

A GeoJSON FeatureCollection is returned containing the query results.

Property Description
type A string containing the type of prediction. This field currently returns ether Sunrise or Sunset.
quality A string containing an adjective that describes the predicted quality of a model point.
quality_percent A float containing a numerical representation of where the quality_value falls along the average standard deviation of quality values, adjusted to account for outliers.
quality_value A float containing a numerical description of a model point’s predicted quality.
temperature A float containing the predicted temperature at the place and time in Celsius.
last_updated A string containing the date/time of the conditions observation or processing by the upstream data source, formatted to RFC3339.
imported_at A string containing the date/time of when the point was made available from the API, formatted to RFC3339.
dawn An object containing three strings: astronomical, nautical, and civil. The properties represent the dates/times of the three phases of dawn, returned in the order of their occurrence, formatted to RFC3339.
valid_at A string containing the date/time of when the point’s predicted conditions should occur, formatted to RFC3339.
dusk An object containing three strings: astronomical, nautical, and civil. The properties represent the dates/times of the three phases of dusk, returned in the order of their occurrence, formatted to RFC3339.
source A string containing an abbreviation of the model name that the prediction was generated from.
distance A float representing the distance in kilometers between the point specified by the geo request parameter, and the returned point.

POST Quality

curl -X "POST" "https://sunburst.sunsetwx.com/v1/quality" \
     -H 'Authorization: Bearer TOKEN[6340beaa-7279-4055-a6ec-fc9422ee0ad8]' \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'[
  {
    "type": "sunrise",
    "coords": [
      -77.8600012,
      40.7933949
    ]
  },
  {
    "type": "sunset",
    "coords": [
      -77.8600012,
      40.7933949
    ]
  },
  {
    "type": "sunrise",
    "coords": [
      -77.8600012,
      40.7933949
    ],
    "after": "2018-07-03T07:41:46Z"
  },
  {
    "type": "sunset",
    "coords": [
      -77.8600012,
      40.7933949
    ],
    "after": "2018-07-03T07:41:46Z"
  }
]'

try {
  const now = new Date();
  const thisTimeTomorrow = now.setDate(now.getDate() + 1);

  const resp = await sunburst.batchQuality([
    {
      geo: [40.7933949, -77.8600012],
      type: 'sunrise'
    },
    {
      geo: [40.7933949, -77.8600012],
      type: 'sunset'
    },
    {
      geo: [40.7933949, -77.8600012],
      type: 'sunrise',
      after: thisTimeTomorrow
    },
    {
      geo: [40.7933949, -77.8600012],
      type: 'sunset',
      after: thisTimeTomorrow
    }
  ]);

  resp.forEach(({ collection, error }) => {
    if (error) {
      // Handle individual query errors separately,
      // as some queries may have still succeeded.
      return console.error(error);
    }
    collection.features.forEach(({ geometry, properties }) => {
      const { coordinates } = geometry;
      console.log({ coordinates, properties });
    });
  });
} catch (ex) {
  // Handle general network or parsing errors.
  return console.error(ex);
}

[
  {
    "collection": {
      "type": "FeatureCollection",
      "features": [
        {
          "type": "Feature",
          "geometry": {
            "type": "Point",
            "coordinates": [
              -77.8673,
              40.8043
            ]
          },
          "properties": {
            "type": "Sunrise",
            "quality": "Poor",
            "quality_percent": 21.04,
            "quality_value": -327.115,
            "temperature": 22.07,
            "last_updated": "2018-07-02T00:00:00Z",
            "imported_at": "2018-07-02T02:54:53Z",
            "dawn": {
              "astronomical": "2018-07-02T07:39:00Z",
              "nautical": "2018-07-02T08:29:00Z",
              "civil": "2018-07-02T09:11:00Z"
            },
            "valid_at": "2018-07-02T09:44:00Z",
            "source": "NAM",
            "distance": 1.359
          }
        }
      ]
    }
  },
  {
    "collection": {
      "type": "FeatureCollection",
      "features": [
        {
          "type": "Feature",
          "geometry": {
            "type": "Point",
            "coordinates": [
              -77.8673,
              40.8043
            ]
          },
          "properties": {
            "type": "Sunset",
            "quality": "Fair",
            "quality_percent": 33.67,
            "quality_value": -169.719,
            "temperature": 22.52,
            "last_updated": "2018-07-01T18:00:00Z",
            "imported_at": "2018-07-01T23:11:52Z",
            "valid_at": "2018-07-03T00:47:00Z",
            "dusk": {
              "civil": "2018-07-03T01:20:00Z",
              "nautical": "2018-07-03T02:02:00Z",
              "astronomical": "2018-07-03T02:52:00Z"
            },
            "source": "NAM",
            "distance": 1.359
          }
        }
      ]
    }
  },
  {
    "collection": {
      "type": "FeatureCollection",
      "features": [
        {
          "type": "Feature",
          "geometry": {
            "type": "Point",
            "coordinates": [
              -77.8673,
              40.8043
            ]
          },
          "properties": {
            "type": "Sunrise",
            "quality": "Fair",
            "quality_percent": 43.93,
            "quality_value": -140.017,
            "temperature": 20.28,
            "last_updated": "2018-07-02T00:00:00Z",
            "imported_at": "2018-07-02T05:31:53Z",
            "dawn": {
              "astronomical": "2018-07-03T07:40:00Z",
              "nautical": "2018-07-03T08:30:00Z",
              "civil": "2018-07-03T09:12:00Z"
            },
            "valid_at": "2018-07-03T09:45:00Z",
            "source": "NAM",
            "distance": 1.359
          }
        }
      ]
    }
  },
  {
    "collection": {
      "type": "FeatureCollection",
      "features": [
        {
          "type": "Feature",
          "geometry": {
            "type": "Point",
            "coordinates": [
              -77.75,
              40.75
            ]
          },
          "properties": {
            "type": "Sunset",
            "quality": "Poor",
            "quality_percent": 21.36,
            "quality_value": -282.158,
            "temperature": 27.45,
            "last_updated": "2018-07-02T00:00:00Z",
            "imported_at": "2018-07-02T04:10:26Z",
            "valid_at": "2018-07-04T00:46:00Z",
            "dusk": {
              "civil": "2018-07-04T01:19:00Z",
              "nautical": "2018-07-04T02:01:00Z",
              "astronomical": "2018-07-04T02:51:00Z"
            },
            "source": "GFS",
            "distance": 10.445
          }
        }
      ]
    }
  }
]

Required Scope: predictions

POST /v1/quality returns an array of queries containing quality prediction results within a collection property or an error message and status_code within an error property.

The request body should be a JSON-formatted array of objects containing the request parameters listed for the GET Quality endpoint.

For more details about the input or output of this endpoint, see the example or the reference for the GET Quality endpoint.


Account

POST Account Password Reset

curl -X "POST" "https://sunburst.sunsetwx.com/v1/account/password/reset" \
  -d "email=EMAIL[example@example.com]"

try {
  const resp = await sunburst.passwordReset({
    email: 'EMAIL[example@example.com]'
  });
  console.log(resp);
} catch (ex) {
  return console.error(ex);
}

{
  "message": "If the email was registered to a valid account, a reset confirmation was sent."
}

POST /v1/account/password/reset allows you to reset an account password by supplying the email address associated with the account. If successful, a confirmation message will be sent to the supplied email address.

Request Body Parameters

Parameter Description
email ✔ A string that contains an email address associated with an account.

✔ == Required Parameter

Response Parameters

Parameter Description
message A string that contains a status message related to the request.

POST Account Email

curl -X "POST" "https://sunburst.sunsetwx.com/v1/account/email" \
  -H "Authorization: Bearer TOKEN[6340beaa-7279-4055-a6ec-fc9422ee0ad8]" \
  -d "new_email=EMAIL[example@example.com]" \
  -d "password=PASSWORD[Pr1ndl3a$85012]"

try {
  const resp = await sunburst.updateEmail({
    newEmail: 'EMAIL[example.new@example.com]',
    password: 'PASSWORD[Pr1ndl3a$85012]'
  });
  console.log(resp);
} catch (ex) {
  return console.error(ex);
}

{
  "message": "If the email was registered to a valid account, a reset confirmation was sent."
}

Required Scope: account

POST /v1/account/email changes the email address associated with an account.

Request Body Parameters

Parameter Description
new_email ✔ A string that contains a new email address to be associated with the account.
password ✔ A string that contains a valid password for the account.

✔ == Required Parameter

Response Parameters

Parameter Description
message A string that contains a status message related to the request.


GET Account Sessions

curl "https://sunburst.sunsetwx.com/v1/account/sessions" \
  -H "Authorization: Bearer TOKEN[6340beaa-7279-4055-a6ec-fc9422ee0ad8]"

try {
  const resp = await sunburst.sessions();
  console.log(resp);
} catch (ex) {
  return console.error(ex);
}

[
  {
    "id": "d7430d22-ada6-484e-83a5-e700077be4e9",
    "type": "access",
    "ip": "10.0.0.10",
    "client": "Paw/3.1.1 (Macintosh; OS X/10.12.5) GCDHTTPRequest",
    "created_at": "2017-05-29T10:31:37Z",
    "expires_at": "2017-05-29T16:31:38Z"
  },
  {
    "id": "87258e73-fd6a-4fda-b31d-e0ea75d8600f",
    "type": "access",
    "ip": "10.0.0.10",
    "client": "Paw/3.1.1 (Macintosh; OS X/10.12.5) GCDHTTPRequest",
    "created_at": "2017-05-29T10:31:21Z",
    "expires_at": "2017-05-29T16:31:22Z"
  },
  {
    "id": "b2c4d9e2-bd25-47ba-96a9-c8d5fb8dd1e9",
    "type": "permanent",
    "ip": "10.0.0.10",
    "client": "Paw/3.1.1 (Macintosh; OS X/10.12.5) GCDHTTPRequest",
    "created_at": "2017-05-29T10:31:18Z",
    "expires_at": "0001-01-01T00:00:00Z"
  }
]

Required Scope: account

GET /v1/account/sessions returns an array of matching session metadata associated with the account.

Request URL Search Parameters

Parameter Description
type A string that contains a valid login type. Used to return only sessions with a matching type.

✔ == Required Parameter

Response Parameters

Parameter Description
id A string that contains a valid session ID to be used for account authentication.
type A string that contains a valid login type.
ip A string that contains the IP address that was used to create the token.
client A string that contains the contents of the user-agent HTTP header that was submitted when the session was created.
created_at A string containing the date/time of when the session was created, formatted to RFC3339.
expires_at A string containing the date/time of when the session will be removed, or will otherwise become invalid, formatted to RFC3339.


DELETE Account Session ID

curl -X "DELETE" "https://sunburst.sunsetwx.com/v1/account/session/SESSION_ID[f78fe615-8eb1-48c4-be21-e5f4f437e8ba]" \
  -H "Authorization: Bearer TOKEN[6340beaa-7279-4055-a6ec-fc9422ee0ad8]"

try {
  const resp = await sunburst.deleteSessionById({
    id: 'SESSION_ID[f78fe615-8eb1-48c4-be21-e5f4f437e8ba]'
  });
  console.log(resp);
} catch (ex) {
  return console.error(ex);
}

{
  "message": "The session was successfully removed."
}

Required Scope: account

DELETE /v1/account/session/:client_id removes an existing session pair based on the given session Client ID string in the URL path.

Request URL Path Parameters

Parameter Description
id ✔ A string that contains a valid session client identifier to be used for account authentication.

✔ == Required Parameter

Response Parameters

Parameter Description
message A string that contains a status message related to the request.


DELETE Account Sessions

curl -X "DELETE" "https://sunburst.sunsetwx.com/v1/account/sessions" \
  -H "Authorization: Bearer TOKEN[6340beaa-7279-4055-a6ec-fc9422ee0ad8]" \
  -d "type=remember_me"

try {
  const resp = await sunburst.deleteSessions();
  console.log(resp);
} catch (ex) {
  return console.error(ex);
}

{
  "message": "All matching sessions have been successfully removed."
}

Required Scope: account

DELETE /v1/account/sessions removes all matching sessions from the account.

Request Body Parameters

Parameter Description
type A string that contains a valid login type. Used to remove only sessions with a matching type. Defaults to removing both access and remember_me sessions.

✔ == Required Parameter

Response Parameters

Parameter Description
message A string that contains a status message related to the request.


DELETE Account

curl -X "DELETE" "https://sunburst.sunsetwx.com/v1/account" \
  -H "Authorization: Bearer TOKEN[6340beaa-7279-4055-a6ec-fc9422ee0ad8]"

try {
  const resp = await sunburst.deleteAccount({
    password: 'PASSWORD[Pr1ndl3a$85012]'
  });
  console.log(resp);
} catch (ex) {
  return console.error(ex);
}

{
  "message": "Account successfully removed."
}

Required Scope: account

DELETE /v1/account permanantly removes the account.

Request Body Parameters

Parameter Description
password ✔ A string that contains a valid password for the account.

✔ == Required Parameter

Response Parameters

Parameter Description
message A string that contains a status message related to the request.


GET Account

curl "https://sunburst.sunsetwx.com/v1/account" \
  -H "Authorization: Bearer TOKEN[6340beaa-7279-4055-a6ec-fc9422ee0ad8]"

try {
  const resp = await sunburst.account();
  console.log(resp);
} catch (ex) {
  return console.error(ex);
}

{
  "email": "EMAIL[email@example.com]",
  "mfa_enabled": false,
  "calls": {
    "quality": {
      "used": 23,
      "free": 227,
      "resets_at": "2018-03-29T02:04:00Z"
    }
  }
}

Required Scope: account

GET /v1/account returns info associated with the account.

Response Parameters

Parameter Description
email A string that contains an email address associated with an account.
mfa_enabled A boolean that is true when multi-factor authentication is enabled.
calls An object that contains child objects, representing endpoints, which contain used, free, and resets_at parameters. calls contains ratelimiting information for various endpoints. used is a number representing how many API calls have been made to the endpoint since the counter reset. free is a number representing how many additional API calls can be made to the endpoint from the time of the request until the time that the counter resets. resets_at is a string containing the time that the counters for the endpoint will reset, formatted to RFC3339.


GET Account MFA

curl "https://sunburst.sunsetwx.com/v1/account/mfa" \
  -H "Authorization: Bearer TOKEN[6340beaa-7279-4055-a6ec-fc9422ee0ad8]"

try {
  const resp = await sunburst.mfa();
  console.log(resp);
} catch (ex) {
  return console.error(ex);
}

{
  "enabled": true,
  "recovery_codes": [
    "BjSr-4D42",
    "GvT5-4F9t"
  ]
}

Required Scope: account

GET /v1/account/mfa returns the current multi-factor authentication settings.

Response Parameters

Parameter Description
enabled A boolean that is true when multi-factor authentication is enabled.
recovery_codes An array of string values that can be used in place of a passcode when a device used for authentication with MFA is misplaced. Recovery codes can only be used once. When all recovery codes are erased, a new list is generated. Setting or resetting an MFA secret regenerates the list of recovery codes.


POST Account MFA

curl -X "POST" "https://sunburst.sunsetwx.com/v1/account/mfa" \
  -H "Authorization: Bearer TOKEN[6340beaa-7279-4055-a6ec-fc9422ee0ad8]" \
  -d "password=PASSWORD[Pr1ndl3a$85012]"
  -d "secret=IDCULSQLXEVANY3R" \
  -d "passcode=618986"
  -d "enabled=true"

try {
  const resp = await sunburst.updateMfa({
    password: 'PASSWORD[Pr1ndl3a$85012]',
    secret: 'IDCULSQLXEVANY3R',
    passcode: '618986',
    enabled: true
  });
  console.log(resp);
} catch (ex) {
  return console.error(ex);
}

{
  "message": "Multi-factor authentication settings successfully updated.",
  "enabled": true,
  "recovery_codes": [
    "BjSr-4D42",
    "GvT5-4F9t"
  ]
}

Required Scope: account

POST /v1/account/mfa updates multi-factor authentication settings.

Request Body Parameters

Parameter Description
password ✔ A string that contains a valid password for the account.
secret A string that contains a TOTP secret code. Valid secrets consist of between 10 and 20 pseudorandom bytes encoded in Base32, with = padding characters removed. Setting or changing this value returns new account recovery codes that should be recorded in a secure location. This value must be entered into a supported multi-factor authentication client, such as Google Authenticator, and a passcode from the device entered into the passcode parameter to confirm the new secret code.
passcode An integer that contains a temporary passcode from a supported multi-factor authentication client, such as Google Authenticator, used to confirm the new secret code.
enabled A boolean that sets whether multi-factor authentication is enabled, which requires a passcode to be entered with an email address and password during each login.

✔ == Required Parameter

Response Parameters

Parameter Description
message A string that contains a status message related to the request.
enabled A boolean that is true when multi-factor authentication is enabled.
recovery_codes An array of string values that can be used in place of a passcode when a device used for authentication with MFA is misplaced. Recovery codes can only be used once. When all recovery codes are erased, a new list is generated. Setting or resetting an MFA secret regenerates the list of recovery codes.


Limits

This section explains the two types of request limits and how to check usage info.

Requests per Second

Up to 20 requests can be made per IP address, per second, for the following endpoints:

Up to 1 request can be made per IP address, per second, for the following endpoints:

Requests per Day

Up to 250 requests can be made within a 24 hour window, per endpoint, starting when the first request is made, for the following endpoints:

Contact us if your account needs to make more requests.

Checking Usage

On endpoints with specific account-based usage limits, we use three HTTP header fields to convey the request limits. These headers are shown when sending requests using the all scope:

ratelimit-limit

An integer representing the total number of requests that the account can make within a 24 hour window.

ratelimit-reset

An integer representing the number of seconds until the request limit resets to the value in the ratelimit-limit field.

ratelimit-remaining

An integer representing the number of requests that have been made so far, since the last reset.

Quality predictions use one request for every 32.18688km in the radius.

To add perspective: using a radius of 32.18688km returns around six points (GeoJSON Features) when using the GFS model (~28 km horizontal resolution), and returns around 406 points when using the NAM model (~3 km horizontal resolution).

This information is also available by querying the GET Account endpoint.

Versions

Documentation Versions

2018

Version MM/DD URL
1.1.1 09/03 https://sunburst.sunsetwx.com/v1/docs/
1.1.0 07/02

2017

Version MM/DD URL
1.0.0 06/15 https://sunburst.sunsetwx.com/v1/docs/1.0.0/

Support

If you need help with using the Sunburst API, or have found a bug, please contact the development team at: team@sunsetwx.com.


shell javascript