NAV Navbar
Logo
shell javascript

Introduction

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [
          -106.75,
          35
        ]
      },
      "properties": {
        "type": "Sunset",
        "quality": "Great",
        "quality_percent": 86.90,
        "quality_value": 134.998,
        "temperature": 19.75,
        "last_updated": "2017-05-29T00:00:00Z",
        "imported_at": "2017-05-29T03:49:21Z",
        "valid_at": "2017-05-30T02:14:00Z",
        "dusk": {
          "civil": "2017-05-30T02:43:00Z",
          "nautical": "2017-05-30T03:19:00Z",
          "astronomical": "2017-05-30T03:58:00Z"
        },
        "source": "GFS",
        "distance": 12.989
      }
    },
    ...
  ]
}

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.


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

Registration

In order to use the API system, you must register using the provided API registration key, your email address, and your desired password.

The next section explains the POST /v1/register endpoint, which is currently used to create new accounts.

POST Register

curl "https://sunburst.sunsetwx.com/v1/register" \
  -X "POST" \
  -d "email=EMAIL[email@example.com]" \
  -d "password=PASSWORD[Pr1ndl3a$85012]" \
  -d "key=REG_KEY[NmPBXvcjTqwJCvxkPeU3Cumg]"

# Tip: Pretty-print responses: curl ... | python -m json.tool

Successful responses, along with most error messages, are encoded in JSON.

{
  "message": "Verification email sent."
}

POST /v1/register is used to register an account in order to receive access tokens that are used to make API requests. All parameters are required.

POST Parameters

Parameter Description
email ✔ A string that contains a valid email address to be used for account authentication.
password ✔ A string of eight or more characters, containing at least one uppercase character, one lowercase character, and one number.
key ✔ A 24-character string containing a valid registration key.

✔ == Required Parameter

Response Parameters

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


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&coords=-77.86,40.79 HTTP/1.1
Authorization: Bearer TOKEN[eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJQcml2aWxlZ2VzIjoiVGVzdGVyIiwiVVVJRCI6ImM5NWE1MmFmLTc1OGYtNDYwZS05ODRlLTgwZTc2Mjc2MmVmZCIsImV4cCI6MTQ2NzkyNDU2Nn0.KVAgjq57XRc0j_MttsK0_M1Kt-pRCpt1VbldVlJIESpRVnf35KwfYuiAJ04ewaQdtk0G3jZ5AY5-LRTphHP7vKOOObGhrzx7kXvC6ZSSyylIn7a8x6N7N6uE0zM1xLsCcyQZGQmAF904vRHRPXO5oxiL2oabGfklUFVidiGF0umz46XY1ZXPYyAy0XJ3OuNetLNelnEbPXFznJadGFSoCqc6jhYWJ-yiTCh3sKO9tQThOKl1jBgWac3u-ip3KwXDJMjEhkWBPZ6njiHaGsJhEKXj_GFm-Pg0vO1pic8P3eECUdOzVPqiHfl47nu815dZIcsZSwJn4q8Jxu1uM4TwslFcgP6d2QSGKa11jXDY8dN2LitKgMv-FPI2WDkGCFCkXzBEaAa31GeYEL5yIk_lKV7E7q336uEl6dogL_46T8jR-YekO8Yn495nCO33-BzICTVnxQ-FTnDJ8Pn_ZU3wQnfkGty6AtfY3Db1Tk3EKl2ipPJXBcZhh8VLZR0dN_TFT-TOprw8vuIlia0Q2EDsaQe2pRRNATsRT0dfFXv0jYg0M2lEIOqshpXSNSmTkJJNmJ6pCpd4ch0O_QSgeNZZodTanzPJvm4C39UoM3rOVKb7hEKXmYys-CMlEqnuRG8TuUBfAuy5PZaiqmmbRegou6AUG_ApwaBui94qWCUVowI]

The API uses JSON Web Token access tokens for performing API calls/requests. Currently, tokens expire one week after their creation.

Access tokens are granted from a successful authorization, based on ether a traditional email and password pair, or a revokable session ID and key pair.

Revokable sessions are randomly-generated credentials that can be used in place of an email and password pair. They can be revoked individually or all at once.

Login Types

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

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 "https://sunburst.sunsetwx.com/v1/login" \
  -X "POST" \
  -d "email=EMAIL[email@example.com]" \
  -d "password=PASSWORD[Pr1ndl3a$85012]"

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

import Sunburst from 'sunburst.js';

const auth = {
  email: 'EMAIL[email@example.com]',
  password: 'PASSWORD[Pr1ndl3a$85012]'
};

let sunburst = new Sunburst(auth);

// An access token is not retrieved until the first method call.

// By default, access tokens are automatically renewed
// 5 minutes before their expiration time.

// The auth.login method (called automatically) will retry
// 10 times, waiting 5 seconds between attempts.

// This behavior can be modified by passing the below 
// objects to the Sunburst class constructor:

auth.renew = {
  enabled: true, // bool
  offset: -300,  // int (seconds)
  callback: null // function
};

auth.retry = {
  enabled: true, // bool
  tries: 10,     // int
  delay: 5       // int (seconds)
};

let sunburst = new Sunburst(auth);

// Generate a revokable session for logging in.
sunburst.auth.login({ type: 'remember_me' }, session => {
  // Add the session to the sunburst class and use it to
  // renew access tokens.
  sunburst.auth.setSession(session, session => {
    console.log(session);
  });
}, console.error);

// Destructuring for simplicity:
const { login, setSession } = sunburst.auth;
const params = {
  type: 'remember_me'
};

login(params, setSession, console.error);

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",
  "token": "TOKEN[eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJQcml2aWxlZ2VzIjoiVGVzdGVyIiwiVVVJRCI6ImM5NWE1MmFmLTc1OGYtNDYwZS05ODRlLTgwZTc2Mjc2MmVmZCIsImV4cCI6MTQ2NzkyNDU2Nn0.KVAgjq57XRc0j_MttsK0_M1Kt-pRCpt1VbldVlJIESpRVnf35KwfYuiAJ04ewaQdtk0G3jZ5AY5-LRTphHP7vKOOObGhrzx7kXvC6ZSSyylIn7a8x6N7N6uE0zM1xLsCcyQZGQmAF904vRHRPXO5oxiL2oabGfklUFVidiGF0umz46XY1ZXPYyAy0XJ3OuNetLNelnEbPXFznJadGFSoCqc6jhYWJ-yiTCh3sKO9tQThOKl1jBgWac3u-ip3KwXDJMjEhkWBPZ6njiHaGsJhEKXj_GFm-Pg0vO1pic8P3eECUdOzVPqiHfl47nu815dZIcsZSwJn4q8Jxu1uM4TwslFcgP6d2QSGKa11jXDY8dN2LitKgMv-FPI2WDkGCFCkXzBEaAa31GeYEL5yIk_lKV7E7q336uEl6dogL_46T8jR-YekO8Yn495nCO33-BzICTVnxQ-FTnDJ8Pn_ZU3wQnfkGty6AtfY3Db1Tk3EKl2ipPJXBcZhh8VLZR0dN_TFT-TOprw8vuIlia0Q2EDsaQe2pRRNATsRT0dfFXv0jYg0M2lEIOqshpXSNSmTkJJNmJ6pCpd4ch0O_QSgeNZZodTanzPJvm4C39UoM3rOVKb7hEKXmYys-CMlEqnuRG8TuUBfAuy5PZaiqmmbRegou6AUG_ApwaBui94qWCUVowI]",
  "token_exp_sec": 604800
}

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

{
  "message": "Login successful",
  "session": {
    "id": "SESSION_ID[f78fe615-8eb1-48c4-be21-e5f4f437e8ba]",
    "key": "SESSION_KEY[18qwl0htsPX|[!NGQ@[qK{X;[&^EVzaH]"
  }
}

POST /v1/login authenticates a user against their stored authorization credentials and then returns a JSON Web Token if successful.

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

POST Parameters

Parameter Description
email ✔ A string that contains a valid email address to be used for account authentication.
password ✔ A string that is longer than eight characters containing at least one uppercase character, one lowercase character, and one number.
type A string containing a valid login type. Defaults to access.

✔ == Required Parameter

Response Parameters

Parameter Description
message A string that contains a status message related to the request.
token A string that contains a Bearer authorization token.
token_exp_sec An integer representing the number of seconds from the time of the response, until the token expires.
session An object containing populated id and key 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 "https://sunburst.sunsetwx.com/v1/login/session" \
  -X "POST" \
  -d "id=SESSION_ID[f78fe615-8eb1-48c4-be21-e5f4f437e8ba]" \
  -d "key=SESSION_KEY[18qwl0htsPX|[!NGQ@[qK{X;[&^EVzaH]"

import Sunburst from 'sunburst.js';

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

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",
  "token": "TOKEN[eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJQcml2aWxlZ2VzIjoiVGVzdGVyIiwiVVVJRCI6ImM5NWE1MmFmLTc1OGYtNDYwZS05ODRlLTgwZTc2Mjc2MmVmZCIsImV4cCI6MTQ2NzkyNDU2Nn0.KVAgjq57XRc0j_MttsK0_M1Kt-pRCpt1VbldVlJIESpRVnf35KwfYuiAJ04ewaQdtk0G3jZ5AY5-LRTphHP7vKOOObGhrzx7kXvC6ZSSyylIn7a8x6N7N6uE0zM1xLsCcyQZGQmAF904vRHRPXO5oxiL2oabGfklUFVidiGF0umz46XY1ZXPYyAy0XJ3OuNetLNelnEbPXFznJadGFSoCqc6jhYWJ-yiTCh3sKO9tQThOKl1jBgWac3u-ip3KwXDJMjEhkWBPZ6njiHaGsJhEKXj_GFm-Pg0vO1pic8P3eECUdOzVPqiHfl47nu815dZIcsZSwJn4q8Jxu1uM4TwslFcgP6d2QSGKa11jXDY8dN2LitKgMv-FPI2WDkGCFCkXzBEaAa31GeYEL5yIk_lKV7E7q336uEl6dogL_46T8jR-YekO8Yn495nCO33-BzICTVnxQ-FTnDJ8Pn_ZU3wQnfkGty6AtfY3Db1Tk3EKl2ipPJXBcZhh8VLZR0dN_TFT-TOprw8vuIlia0Q2EDsaQe2pRRNATsRT0dfFXv0jYg0M2lEIOqshpXSNSmTkJJNmJ6pCpd4ch0O_QSgeNZZodTanzPJvm4C39UoM3rOVKb7hEKXmYys-CMlEqnuRG8TuUBfAuy5PZaiqmmbRegou6AUG_ApwaBui94qWCUVowI]",
  "token_exp_sec": 604800
}

POST /v1/login/session authenticates a user against stored session credentials and then returns a JSON Web Token if successful.

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

POST Parameters

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

✔ == Required Parameter

Response Parameters

Parameter Description
message A string that contains a status message related to the request.
token A string that contains a Bearer authorization token.
token_exp_sec An integer representing the number of seconds from the time of the response, until the token expires.


POST Logout

curl "https://sunburst.sunsetwx.com/v1/logout" \
  -X "POST" \
  -h "Authorization: Bearer TOKEN[eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJQcml2aWxlZ2VzIjoiVGVzdGVyIiwiVVVJRCI6ImM5NWE1MmFmLTc1OGYtNDYwZS05ODRlLTgwZTc2Mjc2MmVmZCIsImV4cCI6MTQ2NzkyNDU2Nn0.KVAgjq57XRc0j_MttsK0_M1Kt-pRCpt1VbldVlJIESpRVnf35KwfYuiAJ04ewaQdtk0G3jZ5AY5-LRTphHP7vKOOObGhrzx7kXvC6ZSSyylIn7a8x6N7N6uE0zM1xLsCcyQZGQmAF904vRHRPXO5oxiL2oabGfklUFVidiGF0umz46XY1ZXPYyAy0XJ3OuNetLNelnEbPXFznJadGFSoCqc6jhYWJ-yiTCh3sKO9tQThOKl1jBgWac3u-ip3KwXDJMjEhkWBPZ6njiHaGsJhEKXj_GFm-Pg0vO1pic8P3eECUdOzVPqiHfl47nu815dZIcsZSwJn4q8Jxu1uM4TwslFcgP6d2QSGKa11jXDY8dN2LitKgMv-FPI2WDkGCFCkXzBEaAa31GeYEL5yIk_lKV7E7q336uEl6dogL_46T8jR-YekO8Yn495nCO33-BzICTVnxQ-FTnDJ8Pn_ZU3wQnfkGty6AtfY3Db1Tk3EKl2ipPJXBcZhh8VLZR0dN_TFT-TOprw8vuIlia0Q2EDsaQe2pRRNATsRT0dfFXv0jYg0M2lEIOqshpXSNSmTkJJNmJ6pCpd4ch0O_QSgeNZZodTanzPJvm4C39UoM3rOVKb7hEKXmYys-CMlEqnuRG8TuUBfAuy5PZaiqmmbRegou6AUG_ApwaBui94qWCUVowI]"

import Sunburst from 'sunburst.js';

let sunburst = new Sunburst({
  email: 'EMAIL[email@example.com]',
  password: 'PASSWORD[Pr1ndl3a$85012]'
});

sunburst.auth.logout(resp => {
  console.log(resp);
}, err => {
  console.error(err);
});

{
  "message": "Logged out"
}

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

GET Quality

curl "https://sunburst.sunsetwx.com/v1/quality" \
  -d "type=sunset" \
  -d "coords=-77.8600012,40.7933949" \
  -H "Authorization: Bearer TOKEN[eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJQcml2aWxlZ2VzIjoiVGVzdGVyIiwiVVVJRCI6ImM5NWE1MmFmLTc1OGYtNDYwZS05ODRlLTgwZTc2Mjc2MmVmZCIsImV4cCI6MTQ2NzkyNDU2Nn0.KVAgjq57XRc0j_MttsK0_M1Kt-pRCpt1VbldVlJIESpRVnf35KwfYuiAJ04ewaQdtk0G3jZ5AY5-LRTphHP7vKOOObGhrzx7kXvC6ZSSyylIn7a8x6N7N6uE0zM1xLsCcyQZGQmAF904vRHRPXO5oxiL2oabGfklUFVidiGF0umz46XY1ZXPYyAy0XJ3OuNetLNelnEbPXFznJadGFSoCqc6jhYWJ-yiTCh3sKO9tQThOKl1jBgWac3u-ip3KwXDJMjEhkWBPZ6njiHaGsJhEKXj_GFm-Pg0vO1pic8P3eECUdOzVPqiHfl47nu815dZIcsZSwJn4q8Jxu1uM4TwslFcgP6d2QSGKa11jXDY8dN2LitKgMv-FPI2WDkGCFCkXzBEaAa31GeYEL5yIk_lKV7E7q336uEl6dogL_46T8jR-YekO8Yn495nCO33-BzICTVnxQ-FTnDJ8Pn_ZU3wQnfkGty6AtfY3Db1Tk3EKl2ipPJXBcZhh8VLZR0dN_TFT-TOprw8vuIlia0Q2EDsaQe2pRRNATsRT0dfFXv0jYg0M2lEIOqshpXSNSmTkJJNmJ6pCpd4ch0O_QSgeNZZodTanzPJvm4C39UoM3rOVKb7hEKXmYys-CMlEqnuRG8TuUBfAuy5PZaiqmmbRegou6AUG_ApwaBui94qWCUVowI]" \
  -G

import Sunburst from 'sunburst.js';

let sunburst = new Sunburst({
  email: 'EMAIL[email@example.com]',
  password: 'PASSWORD[Pr1ndl3a$85012]'
});

const params = {
  type: 'sunrise',
  coords: [
    -77.8600012,
    40.7933949
  ]
};

// Query for quality forecasts within the default radius using the supplied parameters.
sunburst.quality(params, resp => {
  console.log(resp);
}, err => {
  console.error(err);
});

// Setup an averaging reducer.
const averagingReducer = (acc, val, idx, arr) =>
  idx + 1 !== arr.length ? (
    acc + val
  ) : (
    (acc + val) / arr.length
  );

// Map the selected property and apply the selected reducer.
const reduceFeatureProps = (features, reducer, property) =>
  features
    .map(({ properties }) => properties[property])
    .reduce(reducer);

// Average two numerical properties.
const averageFeatureQuality = resp => {
  const avgPer = reduceFeatureProps(resp.features, averagingReducer, 'quality_percent');

  const avgQuality = {
    label:      sunburst.utils.quality.label(avgPer),
    percent:    avgPer,
    value:      reduceFeatureProps(resp.features, averagingReducer, 'quality_value'),
    source:     resp.features[0].properties.source,
    reportedAt: new Date(Date.now()).toLocaleString()
  };

  console.log('Average Quality:', avgQuality);
};

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [
          -77.8673,
          40.8043
        ]
      },
      "properties": {
        "type": "Sunrise",
        "quality": "Poor",
        "quality_percent": 23.38,
        "quality_value": -235.076,
        "temperature": 5.94,
        "last_updated": "2017-04-04T18:00:00Z",
        "imported_at": "2017-04-04T21:59:18Z",
        "dawn": {
          "astronomical": "2017-04-05T09:12:00Z",
          "nautical": "2017-04-05T09:46:00Z",
          "civil": "2017-04-05T10:20:00Z"
        },
        "valid_at": "2017-04-05T10:47:00Z",
        "source": "NAM",
        "distance": 1.270
      }
    },
    ...
  ]
}

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

GET Parameters

Parameter Description
coords ✔ A string that contains a valid longitude and latitude point, with longitude and latitude values separated by a comma.
type ✔ A string that contains a valid model type: sunrise or sunset.
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.
Default: distance_asc
event_id An integer that corresponds with the next available forecast models for the given event.
Default: Set to the next-occurring event. Typically is set to 0 or 1.
Min-Max:
NAM: 0-1
GFS: 0-4

✔ == Required Parameter

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

Event ID

Setting this value allows for retrieving predictions of sunrises and sunsets that are up to 5 days away.

For example, the default search for the next-occurring quality predictions uses an ID of 0 until the sunrise or sunset event occurs, and then a value of 1 is used until the next set of data is imported into the API, and then 0 is used again.

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 coords request parameter, and the returned point.

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 for an audience of people rather than for study.

Quality Value


Sunrise

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


Sunset

Quality (%) Range
Poor (< 25%) -650 to -224
Fair (< 50%) -224 to -79
Good (< 75%) -79 to 66
Great (<= 100%) 66 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.

Dusk

The dusk property is always returned with Sunset forecast results.


Geolocation

GET Coordinates

curl "https://sunburst.sunsetwx.com/v1/coordinates" \
  -d "location=State College, PA" \
  -H "Authorization: Bearer TOKEN[eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJQcml2aWxlZ2VzIjoiVGVzdGVyIiwiVVVJRCI6ImM5NWE1MmFmLTc1OGYtNDYwZS05ODRlLTgwZTc2Mjc2MmVmZCIsImV4cCI6MTQ2NzkyNDU2Nn0.KVAgjq57XRc0j_MttsK0_M1Kt-pRCpt1VbldVlJIESpRVnf35KwfYuiAJ04ewaQdtk0G3jZ5AY5-LRTphHP7vKOOObGhrzx7kXvC6ZSSyylIn7a8x6N7N6uE0zM1xLsCcyQZGQmAF904vRHRPXO5oxiL2oabGfklUFVidiGF0umz46XY1ZXPYyAy0XJ3OuNetLNelnEbPXFznJadGFSoCqc6jhYWJ-yiTCh3sKO9tQThOKl1jBgWac3u-ip3KwXDJMjEhkWBPZ6njiHaGsJhEKXj_GFm-Pg0vO1pic8P3eECUdOzVPqiHfl47nu815dZIcsZSwJn4q8Jxu1uM4TwslFcgP6d2QSGKa11jXDY8dN2LitKgMv-FPI2WDkGCFCkXzBEaAa31GeYEL5yIk_lKV7E7q336uEl6dogL_46T8jR-YekO8Yn495nCO33-BzICTVnxQ-FTnDJ8Pn_ZU3wQnfkGty6AtfY3Db1Tk3EKl2ipPJXBcZhh8VLZR0dN_TFT-TOprw8vuIlia0Q2EDsaQe2pRRNATsRT0dfFXv0jYg0M2lEIOqshpXSNSmTkJJNmJ6pCpd4ch0O_QSgeNZZodTanzPJvm4C39UoM3rOVKb7hEKXmYys-CMlEqnuRG8TuUBfAuy5PZaiqmmbRegou6AUG_ApwaBui94qWCUVowI]" \
  -G

import Sunburst from 'sunburst.js';

let sunburst = new Sunburst({
  email: 'EMAIL[email@example.com]',
  password: 'PASSWORD[Pr1ndl3a$85012]'
});

const params = {
  location: 'State College, PA'
};

sunburst.coordinates(params, resp => {
  console.log(resp);
}, err => {
  console.error(err);
});

const formatPlaceName = ({ locale, state, country }) => 
  [ locale, state, country ].join(', ');

const logFirstResult = resp => {
  if (resp.features.length > 0) {
    const firstResult = resp.features[0].properties;

    console.log(
      formatPlaceName(firstResult)
    );
  }
};

sunburst.coordinates(params, logFirstResult, console.error);

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [
          -77.86069756761077,
          40.79402591647661
        ]
      },
      "properties": {
        "locale": "State College",
        "region": "Centre County",
        "state": "PA",
        "country": "US"
      }
    },
    ...
  ]
}

GET /v1/coordinates finds the longitude and latitude of a given location.

Sources: OpenStreetMaps, UNdata, U.S. Census Bureau, U.S. Geological Survey

Copyright © OpenStreetMap contributors.

GET Parameters

Parameter Description
location ✔ A string that contains a valid location name.

✔ == Required Parameter

Response Parameters

A GeoJSON FeatureCollection is returned containing the query results.

Property Description
locale A string containing the name of a place that is close to the location.
region A string containing the region of the location.
state A string containing the state or province of the location.
country A string containing the country of the location.


GET Location

curl "https://sunburst.sunsetwx.com/v1/location" \
  -d "coords=-77.8600012,40.7933949" \
  -H "Authorization: Bearer TOKEN[eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJQcml2aWxlZ2VzIjoiVGVzdGVyIiwiVVVJRCI6ImM5NWE1MmFmLTc1OGYtNDYwZS05ODRlLTgwZTc2Mjc2MmVmZCIsImV4cCI6MTQ2NzkyNDU2Nn0.KVAgjq57XRc0j_MttsK0_M1Kt-pRCpt1VbldVlJIESpRVnf35KwfYuiAJ04ewaQdtk0G3jZ5AY5-LRTphHP7vKOOObGhrzx7kXvC6ZSSyylIn7a8x6N7N6uE0zM1xLsCcyQZGQmAF904vRHRPXO5oxiL2oabGfklUFVidiGF0umz46XY1ZXPYyAy0XJ3OuNetLNelnEbPXFznJadGFSoCqc6jhYWJ-yiTCh3sKO9tQThOKl1jBgWac3u-ip3KwXDJMjEhkWBPZ6njiHaGsJhEKXj_GFm-Pg0vO1pic8P3eECUdOzVPqiHfl47nu815dZIcsZSwJn4q8Jxu1uM4TwslFcgP6d2QSGKa11jXDY8dN2LitKgMv-FPI2WDkGCFCkXzBEaAa31GeYEL5yIk_lKV7E7q336uEl6dogL_46T8jR-YekO8Yn495nCO33-BzICTVnxQ-FTnDJ8Pn_ZU3wQnfkGty6AtfY3Db1Tk3EKl2ipPJXBcZhh8VLZR0dN_TFT-TOprw8vuIlia0Q2EDsaQe2pRRNATsRT0dfFXv0jYg0M2lEIOqshpXSNSmTkJJNmJ6pCpd4ch0O_QSgeNZZodTanzPJvm4C39UoM3rOVKb7hEKXmYys-CMlEqnuRG8TuUBfAuy5PZaiqmmbRegou6AUG_ApwaBui94qWCUVowI]" \
  -G

import Sunburst from 'sunburst.js';

let sunburst = new Sunburst({
  email: 'EMAIL[email@example.com]',
  password: 'PASSWORD[Pr1ndl3a$85012]'
});

const params = {
  coords: [
    -77.8600012,
    40.7933949
  ]
};

sunburst.location(params, resp => {
  console.log(resp);
}, err => {
  console.error(err);
});

const formatPlaceName = ({ locale, state, country }) => 
  [ locale, state, country ].join(', ');

const logPlace = resp => {
  console.log(
    formatPlaceName(resp.properties)
  );
};

sunburst.location(params, logPlace, console.error);

{
  "type": "Feature",
  "geometry": {
    "type": "Point",
    "coordinates": [
      -77.86069756761077,
      40.79402591647661
    ]
  },
  "properties": {
    "locale": "State College",
    "region": "Centre County",
    "state": "PA",
    "country": "US"
  }
}

GET /v1/location finds the location name for a given longitude and latitude.

Sources: OpenStreetMaps, UNdata, U.S. Census Bureau, U.S. Geological Survey

Copyright © OpenStreetMap contributors.

GET Parameters

Parameter Description
coords ✔ A string that contains a valid longitude and latitude point, with longitude and latitude values separated by a comma.

✔ == Required Parameter

Response Parameters

A GeoJSON Feature is returned containing the query results.

Property Description
locale A string containing the name of a place that is close to the location.
region A string containing the region of the location.
state A string containing the state or province of the location.
country A string containing the country of the location.


Account

POST Account Password Reset

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

import Sunburst from 'sunburst.js';

let sunburst = new Sunburst();

const params = { email: 'EMAIL[example@example.com]' };

sunburst.account.passwordReset(params, resp => {
  console.log(resp);
}, err => {
  console.error(err);
});

{
  "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.

POST Parameters

Parameter Description
email ✔ A string that contains a valid email address to be used for account authentication.

✔ == 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[eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJQcml2aWxlZ2VzIjoiVGVzdGVyIiwiVVVJRCI6ImM5NWE1MmFmLTc1OGYtNDYwZS05ODRlLTgwZTc2Mjc2MmVmZCIsImV4cCI6MTQ2NzkyNDU2Nn0.KVAgjq57XRc0j_MttsK0_M1Kt-pRCpt1VbldVlJIESpRVnf35KwfYuiAJ04ewaQdtk0G3jZ5AY5-LRTphHP7vKOOObGhrzx7kXvC6ZSSyylIn7a8x6N7N6uE0zM1xLsCcyQZGQmAF904vRHRPXO5oxiL2oabGfklUFVidiGF0umz46XY1ZXPYyAy0XJ3OuNetLNelnEbPXFznJadGFSoCqc6jhYWJ-yiTCh3sKO9tQThOKl1jBgWac3u-ip3KwXDJMjEhkWBPZ6njiHaGsJhEKXj_GFm-Pg0vO1pic8P3eECUdOzVPqiHfl47nu815dZIcsZSwJn4q8Jxu1uM4TwslFcgP6d2QSGKa11jXDY8dN2LitKgMv-FPI2WDkGCFCkXzBEaAa31GeYEL5yIk_lKV7E7q336uEl6dogL_46T8jR-YekO8Yn495nCO33-BzICTVnxQ-FTnDJ8Pn_ZU3wQnfkGty6AtfY3Db1Tk3EKl2ipPJXBcZhh8VLZR0dN_TFT-TOprw8vuIlia0Q2EDsaQe2pRRNATsRT0dfFXv0jYg0M2lEIOqshpXSNSmTkJJNmJ6pCpd4ch0O_QSgeNZZodTanzPJvm4C39UoM3rOVKb7hEKXmYys-CMlEqnuRG8TuUBfAuy5PZaiqmmbRegou6AUG_ApwaBui94qWCUVowI]"

import Sunburst from 'sunburst.js';

let sunburst = new Sunburst({
  email: 'EMAIL[email@example.com]',
  password: 'PASSWORD[Pr1ndl3a$85012]'
});

sunburst.account.getSessions({}, resp => {
  console.log(resp);
}, err => {
  console.error(err);
});

[
  {
    "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"
  }
]

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

GET 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 "https://sunburst.sunsetwx.com/v1/account/session/SESSION_ID[f78fe615-8eb1-48c4-be21-e5f4f437e8ba]" \
  -X "DELETE" \
  -H "Authorization: Bearer TOKEN[eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJQcml2aWxlZ2VzIjoiVGVzdGVyIiwiVVVJRCI6ImM5NWE1MmFmLTc1OGYtNDYwZS05ODRlLTgwZTc2Mjc2MmVmZCIsImV4cCI6MTQ2NzkyNDU2Nn0.KVAgjq57XRc0j_MttsK0_M1Kt-pRCpt1VbldVlJIESpRVnf35KwfYuiAJ04ewaQdtk0G3jZ5AY5-LRTphHP7vKOOObGhrzx7kXvC6ZSSyylIn7a8x6N7N6uE0zM1xLsCcyQZGQmAF904vRHRPXO5oxiL2oabGfklUFVidiGF0umz46XY1ZXPYyAy0XJ3OuNetLNelnEbPXFznJadGFSoCqc6jhYWJ-yiTCh3sKO9tQThOKl1jBgWac3u-ip3KwXDJMjEhkWBPZ6njiHaGsJhEKXj_GFm-Pg0vO1pic8P3eECUdOzVPqiHfl47nu815dZIcsZSwJn4q8Jxu1uM4TwslFcgP6d2QSGKa11jXDY8dN2LitKgMv-FPI2WDkGCFCkXzBEaAa31GeYEL5yIk_lKV7E7q336uEl6dogL_46T8jR-YekO8Yn495nCO33-BzICTVnxQ-FTnDJ8Pn_ZU3wQnfkGty6AtfY3Db1Tk3EKl2ipPJXBcZhh8VLZR0dN_TFT-TOprw8vuIlia0Q2EDsaQe2pRRNATsRT0dfFXv0jYg0M2lEIOqshpXSNSmTkJJNmJ6pCpd4ch0O_QSgeNZZodTanzPJvm4C39UoM3rOVKb7hEKXmYys-CMlEqnuRG8TuUBfAuy5PZaiqmmbRegou6AUG_ApwaBui94qWCUVowI]"

import Sunburst from 'sunburst.js';

let sunburst = new Sunburst({
  email: 'EMAIL[email@example.com]',
  password: 'PASSWORD[Pr1ndl3a$85012]'
});

sunburst.account.deleteSessionByID(SESSION_ID[f78fe615-8eb1-48c4-be21-e5f4f437e8ba], resp => {
  console.log(resp);
}, err => {
  console.error(err);
});

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

DELETE /v1/account/session/:id removes an existing session pair based on the given ID string in the URI.

URI Path Parameters

Parameter Description
id ✔ A string that contains a valid session ID 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 "https://sunburst.sunsetwx.com/v1/account/sessions" \
  -X "DELETE" \
  -d "type=remember_me" \
  -H "Authorization: Bearer TOKEN[eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJQcml2aWxlZ2VzIjoiVGVzdGVyIiwiVVVJRCI6ImM5NWE1MmFmLTc1OGYtNDYwZS05ODRlLTgwZTc2Mjc2MmVmZCIsImV4cCI6MTQ2NzkyNDU2Nn0.KVAgjq57XRc0j_MttsK0_M1Kt-pRCpt1VbldVlJIESpRVnf35KwfYuiAJ04ewaQdtk0G3jZ5AY5-LRTphHP7vKOOObGhrzx7kXvC6ZSSyylIn7a8x6N7N6uE0zM1xLsCcyQZGQmAF904vRHRPXO5oxiL2oabGfklUFVidiGF0umz46XY1ZXPYyAy0XJ3OuNetLNelnEbPXFznJadGFSoCqc6jhYWJ-yiTCh3sKO9tQThOKl1jBgWac3u-ip3KwXDJMjEhkWBPZ6njiHaGsJhEKXj_GFm-Pg0vO1pic8P3eECUdOzVPqiHfl47nu815dZIcsZSwJn4q8Jxu1uM4TwslFcgP6d2QSGKa11jXDY8dN2LitKgMv-FPI2WDkGCFCkXzBEaAa31GeYEL5yIk_lKV7E7q336uEl6dogL_46T8jR-YekO8Yn495nCO33-BzICTVnxQ-FTnDJ8Pn_ZU3wQnfkGty6AtfY3Db1Tk3EKl2ipPJXBcZhh8VLZR0dN_TFT-TOprw8vuIlia0Q2EDsaQe2pRRNATsRT0dfFXv0jYg0M2lEIOqshpXSNSmTkJJNmJ6pCpd4ch0O_QSgeNZZodTanzPJvm4C39UoM3rOVKb7hEKXmYys-CMlEqnuRG8TuUBfAuy5PZaiqmmbRegou6AUG_ApwaBui94qWCUVowI]"

import Sunburst from 'sunburst.js';

let sunburst = new Sunburst({
  email: 'EMAIL[email@example.com]',
  password: 'PASSWORD[Pr1ndl3a$85012]'
});

sunburst.account.deleteSessions({ type: 'remember_me' }, resp => {
  console.log(resp);
}, err => {
  console.error(err);
});

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

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

DELETE Parameters

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

✔ == Required Parameter

Response Parameters

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


DELETE Account

curl "https://sunburst.sunsetwx.com/v1/account" \
  -X "DELETE" \
  -H "Authorization: Bearer TOKEN[eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJQcml2aWxlZ2VzIjoiVGVzdGVyIiwiVVVJRCI6ImM5NWE1MmFmLTc1OGYtNDYwZS05ODRlLTgwZTc2Mjc2MmVmZCIsImV4cCI6MTQ2NzkyNDU2Nn0.KVAgjq57XRc0j_MttsK0_M1Kt-pRCpt1VbldVlJIESpRVnf35KwfYuiAJ04ewaQdtk0G3jZ5AY5-LRTphHP7vKOOObGhrzx7kXvC6ZSSyylIn7a8x6N7N6uE0zM1xLsCcyQZGQmAF904vRHRPXO5oxiL2oabGfklUFVidiGF0umz46XY1ZXPYyAy0XJ3OuNetLNelnEbPXFznJadGFSoCqc6jhYWJ-yiTCh3sKO9tQThOKl1jBgWac3u-ip3KwXDJMjEhkWBPZ6njiHaGsJhEKXj_GFm-Pg0vO1pic8P3eECUdOzVPqiHfl47nu815dZIcsZSwJn4q8Jxu1uM4TwslFcgP6d2QSGKa11jXDY8dN2LitKgMv-FPI2WDkGCFCkXzBEaAa31GeYEL5yIk_lKV7E7q336uEl6dogL_46T8jR-YekO8Yn495nCO33-BzICTVnxQ-FTnDJ8Pn_ZU3wQnfkGty6AtfY3Db1Tk3EKl2ipPJXBcZhh8VLZR0dN_TFT-TOprw8vuIlia0Q2EDsaQe2pRRNATsRT0dfFXv0jYg0M2lEIOqshpXSNSmTkJJNmJ6pCpd4ch0O_QSgeNZZodTanzPJvm4C39UoM3rOVKb7hEKXmYys-CMlEqnuRG8TuUBfAuy5PZaiqmmbRegou6AUG_ApwaBui94qWCUVowI]"

import Sunburst from 'sunburst.js';

let sunburst = new Sunburst({
  email: 'EMAIL[email@example.com]',
  password: 'PASSWORD[Pr1ndl3a$85012]'
});

sunburst.account.delete(resp => {
  console.log(resp);
}, err => {
  console.error(err);
});

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

DELETE /v1/account permanantly removes the account.

Response Parameters

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


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:

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 these endpoints:

Contact us if your account needs to make more requests.

Checking Usage

We use three HTTP header fields to convey the request limits:

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).

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