SDSP SERVICES

Lighting Services

Solar Lighting

This service provides times for sunrise, sunset and varying twilight conditions. In the outputs of this service, there are Am and Pm twilight times. These times represent the twilight before sunrise and after sunset respectively.

For locations above the Arctic circle or below the Antarctic circle, the sun may not rise or set on that day, depending on the time of year. Four other outputs will be pertinent in these cases. If the sun does not set, the output setting ContinuouslyAboveHorizon will be true and IsRiseDefined and IsSetDefined will both be false. Similar conditions hold for when the sun does not rise, with the appropriate values set for IsRiseDefined, IsSetDefined and ContinuouslyBelowHorizon.

API Paths
lighting/site
lighting/pointToPoint
HTTP Method
POST
Input Format

All lighting service requests can be performed at a site or along a point to point route, as specified in the API paths above. For the Path element below, use the JSON from the point to point route or a site location. The service will use the route's start and stop times if a route is used. If a site is used, you must set the AnalysisStart and AnalysisStop times below.

Note that the lighting services only use the Step element, supplied in the Path's OutputSettings, when the route service is used. Also, all times are input in UTC. Finally, all times are output in UTC unless the OutputTimeOffset values is set to something different that 0.

{
    "Path": {}
    "AnalysisStart": "2018-04-09",
    "AnalysisStop": "2018-04-11",
    "OutputTimeOffset": -4.0
}
Path
JSON object defining the location point(s) on which solar lighting will be calculated.
AnalysisStart
The start date of the solar lighting calculations. Required for site paths, ignored when the Path is a route. You can add a time to the parameter, but it will be ignored, only the date is used.
AnalysisStop
The stop date of the solar lighting calculation. Required for site paths, ignored when the Path is a route. You can add a time to the parameter, but it will be ignored, only the date is used.
OutputTimeOffset
The number of hours you'd like the output times to be shifted by. Example, to convert the times to Eastern time, set OutputTimeOffset to -4.0. Optional, when not included, or if the value is 0, the output times are in UTC.
Input Sample: Single Site

This sample shows the solar lighting info for three days at a single site. 

{
    "Path": {
        "Location": {
            "Latitude": 39.0,
            "Longitude": -75.77,
            "Altitude": 0
        }
    },
    "AnalysisStart": "2018-04-09",
    "AnalysisStop": "2018-04-11",
    "OutputTimeOffset": -4
}
Output Sample: Single Site
{
    "Lighting": [
        {
            "AstronomicalTwilightAmStart": "2018-04-09T05:02:13.3531523-04:00",
            "AstronomicalTwilightAmStop": "2018-04-09T05:35:48.3597812-04:00",
            "AstronomicalTwilightPmStart": "2018-04-09T20:34:19.7666117-04:00",
            "AstronomicalTwilightPmStop": "2018-04-09T21:08:04.1423911-04:00",
            "NauticalTwilightAmStart": "2018-04-09T05:35:48.3597812-04:00",
            "NauticalTwilightAmStop": "2018-04-09T06:08:10.4677391-04:00",
            "NauticalTwilightPmStart": "2018-04-09T20:01:50.7593491-04:00",
            "NauticalTwilightPmStop": "2018-04-09T20:34:19.7666117-04:00",
            "CivilTwilightAmStart": "2018-04-09T06:08:10.4677391-04:00",
            "CivilTwilightAmStop": "2018-04-09T06:35:24.756639-04:00",
            "CivilTwilightPmStart": "2018-04-09T19:34:31.8139969-04:00",
            "CivilTwilightPmStop": "2018-04-09T20:01:50.7593491-04:00",
            "Sunrise": "2018-04-09T06:35:24.756639-04:00",
            "Sunset": "2018-04-09T19:34:31.8139969-04:00",
            "ContinuouslyBelowHorizon": false,
            "ContinuouslyAboveHorizon": false,
            "IsRiseDefined": true,
            "IsSetDefined": true
        },
        {
            "AstronomicalTwilightAmStart": "2018-04-10T05:00:26.1674639-04:00",
            "AstronomicalTwilightAmStop": "2018-04-10T05:34:09.3756428-04:00",
            "AstronomicalTwilightPmStart": "2018-04-10T20:35:26.769963-04:00",
            "AstronomicalTwilightPmStop": "2018-04-10T21:09:19.5279138-04:00",
            "NauticalTwilightAmStart": "2018-04-10T05:34:09.3756428-04:00",
            "NauticalTwilightAmStop": "2018-04-10T06:06:36.9812371-04:00",
            "NauticalTwilightPmStart": "2018-04-10T20:02:52.1497862-04:00",
            "NauticalTwilightPmStop": "2018-04-10T20:35:26.769963-04:00",
            "CivilTwilightAmStart": "2018-04-10T06:06:36.9812371-04:00",
            "CivilTwilightAmStop": "2018-04-10T06:33:54.4679584-04:00",
            "CivilTwilightPmStart": "2018-04-10T19:35:29.9380579-04:00",
            "CivilTwilightPmStop": "2018-04-10T20:02:52.1497862-04:00",
            "Sunrise": "2018-04-10T06:33:54.4679584-04:00",
            "Sunset": "2018-04-10T19:35:29.9380579-04:00",
            "ContinuouslyBelowHorizon": false,
            "ContinuouslyAboveHorizon": false,
            "IsRiseDefined": true,
            "IsSetDefined": true
        },
        {
            "AstronomicalTwilightAmStart": "2018-04-11T04:58:39.0198503-04:00",
            "AstronomicalTwilightAmStop": "2018-04-11T05:32:30.6547429-04:00",
            "AstronomicalTwilightPmStart": "2018-04-11T20:36:34.092548-04:00",
            "AstronomicalTwilightPmStop": "2018-04-11T21:10:35.4566911-04:00",
            "NauticalTwilightAmStart": "2018-04-11T05:32:30.6547429-04:00",
            "NauticalTwilightAmStop": "2018-04-11T06:05:03.9131295-04:00",
            "NauticalTwilightPmStart": "2018-04-11T20:03:53.6959741-04:00",
            "NauticalTwilightPmStop": "2018-04-11T20:36:34.092548-04:00",
            "CivilTwilightAmStart": "2018-04-11T06:05:03.9131295-04:00",
            "CivilTwilightAmStop": "2018-04-11T06:32:24.7169128-04:00",
            "CivilTwilightPmStart": "2018-04-11T19:36:28.108925-04:00",
            "CivilTwilightPmStop": "2018-04-11T20:03:53.6959741-04:00",
            "Sunrise": "2018-04-11T06:32:24.7169128-04:00",
            "Sunset": "2018-04-11T19:36:28.108925-04:00",
            "ContinuouslyBelowHorizon": false,
            "ContinuouslyAboveHorizon": false,
            "IsRiseDefined": true,
            "IsSetDefined": true
        }
    ]
}
Input Sample: Point to Point Route

This sample shows the solar lighting info for a point to point route. Note that for routes, FlightLightingInfo is calculated at the beginning of the flight. The other output parameters take the whole flight into account however. 

{
    "Path": {
        "Waypoints": [
            {
                "Position": {
                    "Latitude": 39.07096,
                    "Longitude": -75.78509,
                    "Altitude": 600.0
                },
                "Time": "2014-03-25T18:30:00"
            },
            {
                "Position": {
                    "Latitude": 39.06308,
                    "Longitude": -75.78500,
                    "Altitude": 620.0
                },
                "Time": "2014-03-25T18:30:20"
            }
        ]
    },
    "OutputTimeOffset": -4
}
Output Sample: Point to Point Route
{
    "FlightLightingInfo": {
        "AstronomicalTwilightAmStart": "2014-03-25T05:28:43.4987357-04:00",
        "AstronomicalTwilightAmStop": "2014-03-25T06:00:43.5326183-04:00",
        "AstronomicalTwilightPmStart": "2014-03-25T20:18:16.0267256-04:00",
        "AstronomicalTwilightPmStop": "2014-03-25T20:50:22.8752198-04:00",
        "NauticalTwilightAmStart": "2014-03-25T06:00:43.5326183-04:00",
        "NauticalTwilightAmStop": "2014-03-25T06:32:04.6788925-04:00",
        "NauticalTwilightPmStart": "2014-03-25T19:46:49.6696833-04:00",
        "NauticalTwilightPmStop": "2014-03-25T20:18:16.0267256-04:00",
        "CivilTwilightAmStart": "2014-03-25T06:32:04.6788925-04:00",
        "CivilTwilightAmStop": "2014-03-25T06:58:47.089726-04:00",
        "CivilTwilightPmStart": "2014-03-25T19:20:03.6717008-04:00",
        "CivilTwilightPmStop": "2014-03-25T19:46:49.6696833-04:00",
        "Sunrise": "2014-03-25T06:58:47.089726-04:00",
        "Sunset": "2014-03-25T19:20:03.6717008-04:00",
        "ContinuouslyBelowHorizon": false,
        "ContinuouslyAboveHorizon": false,
        "IsRiseDefined": true,
        "IsSetDefined": true
    },
    "BeginningOfFlightLightingCondition": "Daylight",
    "EndOfFlightLightingCondition": "Daylight",
    "SunriseBetweenStartAndEnd": false,
    "SunsetBetweenStartAndEnd": false
}

Solar Angles

This service provides the azimuth and elevation (in degrees) of the sun at specified times. The times can all be from a static site or from different points along a route.

API Paths
lighting/angles/site
lighting/angles/pointToPoint
HTTP Method
POST
Input Format

All angle service requests can be performed at a site or along a point to point route, as specified in the API paths above. For the Path element below, use the JSON from the point to point route or a site location. The service will use the route's start and stop times if a route is used. If a site is used, you must set the AnalysisStart and AnalysisStop times below.

Note that the angle services only use the Step element, supplied in the Path's OutputSettings, when the route service is used. Also, all times are input in UTC. Finally, all times are output in UTC unless the OutputTimeOffset values is set to something different that 0.

{
    "Path": {}
    "AnalysisStart": "2018-04-09",
    "AnalysisStop": "2018-04-11",
    "OutputTimeOffset": -4.0
}
Path
JSON object defining the location point(s) on which solar angles will be calculated.
AnalysisStart
The start date of the solar angle calculation. Required for site paths, ignored when the Path is a route. You can add a time to the parameter, but it will be ignored, only the date is used.
AnalysisStop
The stop date of the solar angle calculation. Required for site paths, ignored when the Path is a route. You can add a time to the parameter, but it will be ignored, only the date is used.
OutputTimeOffset
The number of hours you'd like the output times to be shifted by. Example, to convert the times to Eastern time, set OutputTimeOffset to -4.0. Optional, when not included, or if the value is 0, the output times are in UTC.
Input Sample: Single Site

This sample shows the solar angles for the daytime on a given day at a single site. 

{
    "Path": {
        "Location": {
            "Latitude": 39.0,
            "Longitude": -75.77,
            "Altitude": 0
        },
        "OutputSettings": {
            "Step": 7200
        }
    },
    "AnalysisStart": "2018-04-09T11:00",
    "AnalysisStop": "2018-04-09T23:00",
    "OutputTimeOffset": -4
}
Output Sample: Single Site
[
    {
        "Time": "2018-04-09T07:00:00-04:00",
        "Azimuth": 83.318849119597814,
        "Elevation": 3.8989357108618949
    },
    {
        "Time": "2018-04-09T09:00:00-04:00",
        "Azimuth": 102.78794471633078,
        "Elevation": 27.098526841202464
    },
    {
        "Time": "2018-04-09T11:00:00-04:00",
        "Azimuth": 129.95330050093779,
        "Elevation": 48.023841579782164
    },
    {
        "Time": "2018-04-09T13:00:00-04:00",
        "Azimuth": 177.80634304086993,
        "Elevation": 58.718891237922143
    },
    {
        "Time": "2018-04-09T15:00:00-04:00",
        "Azimuth": 227.31166530610972,
        "Elevation": 49.415495813662616
    },
    {
        "Time": "2018-04-09T17:00:00-04:00",
        "Azimuth": 255.64928327693772,
        "Elevation": 28.914991940942279
    },
    {
        "Time": "2018-04-09T19:00:00-04:00",
        "Azimuth": 275.3956390242036,
        "Elevation": 5.7914173984610491
    }
]
Input Sample: Point to Point Route

This sample shows the solar angles for a point to point route. 

{
    "Path": {
        "Waypoints": [
            {
                "Position": {
                    "Latitude": 39.07096,
                    "Longitude": -75.78509,
                    "Altitude": 2000.0
                },
                "Time": "2014-03-25T18:30:00"
            },
            {
                "Position": {
                    "Latitude": 39.06308,
                    "Longitude": -75.78500,
                    "Altitude": 2010.0
                },
                "Time": "2014-03-25T18:30:20"
            }
        ],
        "OutputSettings": {
            "Step": 5
        }
    },
    "OutputTimeOffset":-4
}
Output Sample: Point to Point Route
[
    {
        "Time": "2014-03-25T14:30:00-04:00",
        "Azimuth": 211.51268842209117,
        "Elevation": 48.583043708655616
    },
    {
        "Time": "2014-03-25T14:30:05-04:00",
        "Azimuth": 211.5426657019033,
        "Elevation": 48.57627474707548
    },
    {
        "Time": "2014-03-25T14:30:10-04:00",
        "Azimuth": 211.57263483591447,
        "Elevation": 48.5694977851927
    },
    {
        "Time": "2014-03-25T14:30:15-04:00",
        "Azimuth": 211.6025958183501,
        "Elevation": 48.5627128265808
    },
    {
        "Time": "2014-03-25T14:30:20-04:00",
        "Azimuth": 211.63254864345626,
        "Elevation": 48.555919874812162
    }
]

Solar Transit

This service provides the time that the center of the sun passes over 180.0 degrees azimuth for a given location. The elevation at that time is also given, representing the maximum elevation for the sun at that location, for that day.

API Paths
lighting/transit/site
HTTP Method
POST
Input Format

This service request requires that the Path element be a site location. 

{
    "Path": {}
    "AnalysisStart": "2018-04-09",
    "AnalysisStop": "2018-04-11",
    "OutputTimeOffset": -4.0
}
Path
JSON object defining the location point(s) on which solar transit information will be calculated.
AnalysisStart
The start date of the solar transit calculation. Required. You can add a time to the parameter, but it will be ignored, only the date is used.
AnalysisStop
The stop date of the solar transit calculation. Required. You can add a time to the parameter, but it will be ignored, only the date is used.
OutputTimeOffset
The number of hours you'd like the output times to be shifted by. Example, to convert the times to Eastern time, set OutputTimeOffset to -4.0. Optional, when not included, or if the value is 0, the output times are in UTC.
Input Sample: Transit Information at a Site

This sample shows the solar transit information for a site. 

{
    "Path": {
        "Location": {
            "Latitude": 39.0,
            "Longitude": -75.75,
            "Altitude": 0
        }
    },
    "AnalysisStart": "2018-04-09",
    "AnalysisStop": "2018-04-10",
    "OutputTimeOffset": -4
}
Output Sample: Single Site
[
    {
        "Time": "2018-04-09T13:04:33.5196939-04:00",
        "Azimuth": 180.02029979016393,
        "Elevation": 58.737162994273653
    },
    {
        "Time": "2018-04-10T13:04:17.438093-04:00",
        "Azimuth": 180.02053252533128,
        "Elevation": 59.107005527908427
    }
]