RemoteControl plugin HTTP API description

Table of Contents

• Extending the API
• API reference
  • MainService operations (/api/main/)
    • GET operations
      • status
      • plugins
      • view
    • POST operations
      • time
      • focus
      • move
      • view
      • fov
      • window
  • ObjectService operations (/api/objects/)
    • GET operations
      • find
      • info
      • listobjecttypes
      • listobjectsbytype
  • ScriptService operations (/api/scripts/)
    • GET operations
      • list
      • info
      • status
    • POST operations
      • run
      • direct
      • stop
  • SimbadService operations (/api/simbad/)
    • GET operations
      • lookup
  • StelAction operations (/api/stelaction/)
    • GET operations
      • list
    • POST operations
      • do
  • StelProperty operations (/api/stelproperty/)
    • GET operations
      • list
    • POST operations
      • set
  • LocationService operations (/api/location/)
    • GET operations
      • list
      • countrylist
      • planetlist
      • planetimage
    • POST operations
      • setlocationfields
  • LocationSearchService operations (/api/locationsearch/)
    • GET operations
      • search
      • nearby
  • ViewService operations (/api/view/)
    • GET operations
      • listlandscape
      • landscapedescription/
      • listskyculture
      • skyculturedescription/
      • listprojection
      • projectiondescription

The RemoteControl plugin provides an HTTP-based interface to Stellarium, implemented on the server-side through implementations of AbstractAPIService. The APIController maintains the list of registered services, and dispatches HTTP requests to the right service. The API is accessible under the server path /api/. For example, if you have the server running on the default port of 8090, you can access the operation find of the ObjectService to look for objects with moon in their name by accessing

http://localhost:8090/api/objects/find?str=moon
|____________________|___|_______|____|_______|
          |            |     |      |     |------ Standard HTTP query string for parameters (key=value)
          |            |     |      |------------ find operation (defined by service)
          |            |     |------------------- service (e.g. ObjectService)
          |            |------------------------- API prefix (always /api/)
          |-------------------------------------- server access (http://host:port)

Instead of the HTTP remote interface you can also use tools like cURL to access the API remotely. For POST operations, you would use the flag -d to pass parameters. For GET operations, you should use the additional flag -G if parameters are required. Examples:

# retrieve info about the script "double_stars.ssc" with a GET request
curl -G -d 'id=double_stars.ssc' http://localhost:8090/api/scripts/info
# run the script "double_stars.ssc" with a POST request
curl -d 'id=double_stars.ssc' http://localhost:8090/api/scripts/run

If authentication is enabled (see RemoteControl class), HTTP Basic access authentication is expected, with an empty username. HTTPS configuration is currently not implemented, even if the underlying QtWebApp library would allow it.

Most operations return data in the JSON format, allowing it to be easily used in web applications. The format of the returned JSON data is described for each operation below. Some operations return plain text if only simple data is requested, or to confirm the success of an operation: to indicate success "ok" may be returned, in an error case an HTTP error code may be returned together with a string "error: error message" in the response body. Other operations may return HTML or even image data, you can check the returned Content-Type header if you are not sure what to expect.

Extending the API

The simplest way to expose new data through the API is by using the StelProperty system for a property you want to access. In this way, the data is available through the MainService (allowing tracking of changes) and the StelPropertyService (giving a snapshot of current values, metadata information and allowing to change values). You do not need to change/implement a new service in any way for this case.

If you want to expose more complex behaviour, you may need to implement your own AbstractAPIService and register it with the APIController.

API reference

The default services are registered in the RequestHandler::RequestHandler() constructor. They are:

Service	Path	Description
MainService	main	Implements the main API services, including the status operation which can be repeatedly polled to find the current state of the main program, including time, view, location, StelAction and StelProperty state changes, movement, script status ...
ObjectService	objects	Provides operations to look up objects in the Stellarium catalogs.
ScriptService	scripts
SimbadService	simbad	Allows SIMBAD object lookups like SearchDialog uses.
StelActionService	stelaction	Provides services related to StelAction.
StelPropertyService	stelproperty	Provides services related to StelProperty.
LocationService	location	Provides methods to look up location-related information, and change the current location.
LocationSearchService	locationsearch	Provides predefined location search functionality, using the StelLocationMgr.
ViewService	view	Provides services related to the view (landscape, sky culture, projection).

MainService operations (/api/main/)

GET operations

Implemented by MainService::getImpl

status

Parameters: [actionId (Number)] [propId (Number)]
This operation can be polled every few moments to find out if some primary Stellarium state changed. It returns a JSON object with the following format:

{
    //current location information, see StelLocation
    location : {
        name,
        role,
        planet,
        latitude,
        longitude,
        altitude,
        country,
        state,
        landscapeKey
    },
    //current time information
    time : {
        jday,       //current Julian day
        deltaT,     //current deltaT as determined by the current dT algorithm
        gmtShift,   //the timezone shift to GMT
        timeZone,   //the timezone name
        utc,        //the time in UTC time zone as ISO8601 time string
        local,      //the time in local time zone as ISO8601 time string
        isTimeNow,  //if true, the Stellarium time equals the current real-world time
        timerate    //the current time rate (in secs)
    },
    selectioninfo, //string that contains the information of the currently selected object, as returned by StelObject::getInfoString
    view : {
        fov     //current FOV
    },
 
    //the following is only inserted if an actionId parameter was given
    //see below for more info
    actionChanges : {
        id, //currently valid action id, the interface should update its own id to this value
        changes : {
                //a list of boolean actions that changed since the actionId parameter
                <actionName> : <actionValue>
        }
    },
    //the following is only inserted if an propId parameter was given
    //see below for more info
    propertyChanges : {
        id, //currently valid prop id, the interface should update its own id to this value
        changes : {
                //a list of properties that changed since the propId parameter
                <propName> : <propValue>
        }
    }
}

The actionChanges and propertyChanges sections allow a remote interface to track boolean StelAction and/or StelProperty changes. On the initial poll, you should pass -2 as propId and actionId. This indicates to the service that you want a full list of properties/actions and their current values. When receiving the answer, you should set your local propId /actionId to the id contained in actionChanges and propertyChanges, and re-send it with the next request as parameter again. This allows the MainService to find out which changes must be sent to you (it maintains a queue of action/property changes internally, incrementing the ID with each change), and you only have to process the differences instead of everything.

plugins

Returns the list of all known plugins, as a JSON object of format:

{
    //list of known plugins, in format:
    <pluginName> : {
        loadAtStartup,  //if to load the plugin at startup
        loaded,     //if the plugin is currently loaded
        //corresponds to the StelPluginInfo of the plugin
        info : {
                authors,
                contact,
                description,
                displayedName,
                startByDefault,
                version
        }
    }
}

view

Parameters: [coord (j2000|jNow|altAz) ] [ ref (on|off|auto) ]
Returns the current view direction, as a JSON object of format:

{
    //list of view directions, in format:
    "j2000" : "[x,y,z]",
    "jNow"  : "[x,y,z]",
    "altAz" : "[x,y,z]"
}

Without the optional coord, all versions are returned. The returned values are 3D vectors.

x=	cos(δ)*cos(α)
y=	cos(δ)*sin(α)
z=	sin(δ)

For the vector in altAz system, the actually returned values are based on an azimuth Az' counted from South (x=1) towards East (y=1), Az'=180-Az.

x=	cos(alt)*cos(Az')
y=	cos(alt)*sin(Az')
z=	sin(alt)

If the optional parameter ref is given, it governs refraction setting and it applies to the jNow output only. "On" applies refraction, "off" does not apply, and "auto" (or any other value) applies it when atmosphere setting is active.

POST operations

Implemented by MainService::postImpl

time

Parameters: time (Number) timerate (Number)
Sets the current Stellarium simulation time and/or timerate. The time parameter defines the current time (Julian day) as passed to StelCore::setJD. The timerate parameter allows to change the speed at which the simulation time moves (in JDay/sec) as passed to StelCore::setTimeRate.

focus

Parameters: [target (String) | position (JSON Number Array of size 3, i.e. Vec3d)] [mode (String)]
Sets the current app focus/selection. If no parameters are given, the current selection is cleared. If the target parameter was given, the object to be selected is looked up by name (first the localized name is tried, then the english name). If the optional mode parameter is given, it determines how to change the view. The default is 'center' which selects the object and moves it into the view's center. If it is set to 'zoom', it automatically zooms in on the object (StelMovementMgr::autoZoomIn) on selection and automatically zooms out when the selection is cleared. If it is set to 'mark', the selection is just marked, but no view adjustment is done. If the position parameter is used, it is interpreted as a coordinate in the J2000 frame, and focused using StelMovementMgr::moveToJ2000. The mode parameter has no effect here. The target parameter takes precedence over the position parameter, if both are given.

move

Parameters: x (Number) y (Number)
Allows viewport movement, like using the arrow keys in the main program. This allows interfaces to create a "virtual joystick" to move the view manually. This operation defines the intended move direction. x and y define the intended move speed in azimuth and altitude (i.e. a negative x means left). Values of +-1.0 correspond to the same speed as used for the arrow keys. This operation works in conjunction with the update() method - until the movement is stopped (i.e. x and y are zero), or no move command has been received for a specified time (about a second), the movement is performed in the given directions.

view

Parameters: j2000 (Vec3d) | jNow (Vec3d) [ ref (on|off|auto) ] | altAz (Vec3d) | (az (Number) alt (Number))
Sets the view direction. When the j2000 parameter is given (interpreted as JSON Number Array of size 3), it sets the view in J2000 coordinates (see StelMovementMgr::setViewDirectionJ2000). When the jNow parameter is given (interpreted as JSON Number Array of size 3), it sets the view in coordinates of current date. An optional parameter ref governs refraction mode, default auto. When the altAz parameter is given, the 3-element vector is interpreted as if in the rectangular surface direction frame centered on the current location. For example, [1,0,0] would point the view directly south, and [0,1,0] directly east. The last parameter style provides the view in altitude/azimuth spherical coordinates/angles. az and alt must be given in radians. Omitting one value will keep the relevant coordinate unchanged.

fov

Parameters: fov (Number)
Sets the current field-of-view using StelCore::setFov

window

Parameters: w (int) h (int)
Sets the window size using StelMainView::setWindowSize() This can be useful e.g. when Stellarium provides image background inserts via spout.

ObjectService operations (/api/objects/)

GET operations

Implemented by ObjectService::getImpl

find

Parameters: str (String)
Finds objects which match the search string str, which may contain greek/unicode characters like in the SearchDialog. Returns a JSON String array of search matches

info

Parameters: [name (String)]
Parameters: [format (String)] (strings "json" or "map" for JSON, any other value provides HTML)
Returns an info string about the object identified by name in HTML (StelObject::getInfoString) or JSON (StelObject::getInfoMap) format. If no parameter name is given, the currently selected object is used.

listobjecttypes

Returns all object types available in the internal catalogs as a JSON array of objects of format

{
    key,    //the internal key for the object type
    name,   //the english name of the type
    name_i18n //the type name in the current language
}

listobjectsbytype

Parameters: type (String) [english (Number)]
Returns all objects of the specified type. If english is given and it evaluates to a "true" value, the english names will be returned, otherwise the localized names will be returned. Returns a JSON string array.

ScriptService operations (/api/scripts/)

Note

Stellarium must have been built with ENABLE_SCRIPTING (default).

GET operations

Implemented by ScriptService::getImpl

list

Lists all known script files, as a JSON string array.

info

Parameters: id (String) [html (any type)]
Returns information about the script identified by id. If the optional parameter html is present (its value is ignored), the info is formatted using StelScriptMgr::getHtmlDescription and suitable for inclusion into an iframe element, otherwise this operation returns a JSON object of format:

{
    id, //the script ID
    name,   //the english name of the script
    name_localized, //the localized name of the script
    description,    //the english description of the script
    description_localized,  //the localized description of the script
    author, //the author(s) of the script
    license //the license of the script
}

status

Returns the current script status as a JSON object of format:

{
    scriptIsRunning,    //true if a script is running
    runningScriptId     //the currently running script ID
}

Note

The StelScriptMgr also provides a StelProperty StelScriptMgr.runningScriptId that can be used to find out the active script.

POST operations

Implemented by ScriptService::postImpl

run

Parameters: id (String)
Runs the script with the given id. Will fail if a script is currently running.

direct

Parameters: code (String) [useIncludes (Bool)]
Directly executes the given script code. If useIncludes is given and evaluates to true, the standard include folder will be used. Script execution will fail if a script is already running.

stop

Stops the execution of a running script.

SimbadService operations (/api/simbad/)

GET operations

Implemented by SimbadService::getImpl

lookup

Parameters: str (String)
Performs a SIMBAD lookup for the string str using the Stellarium-configured server and returns the results as a JSON object of format

{
    status, //the status of the lookup: either "empty" when nothing was found, "found" when at least 1 result was returned, and "error" if the lookup caused an error
    status_i18n, //a localized status message for display
    errorString, //if the status is "error", this contains more information about it
    results: {
        names : [
                //an array of object names
        ],
        positions : [
                //an array of object positions (i.e. first one corresponds to first name, etc.)
                //format is an array of 3 numbers for each entry, i.e.:
                [1,2,3],...
        ]
    }
}

StelAction operations (/api/stelaction/)

GET operations

Implemented by StelActionService::getImpl

list

Lists all registered StelActions, in the format

{
    //translated StelAction group name
    <groupName> : [
        //all StelActions in the group <groupName>
        <actionName> : {
                id, //the ID of the action
                isCheckable,    //true if the action represents a boolean value
                isChecked,  //if "isCheckable" is true, shows the current boolean state
                text    //the translated description of the action
        }
    ]
}

POST operations

Implemented by StelActionService::postImpl

do

Parameters: id (String)
Triggers or toggles the StelAction specified by id. If it was a boolean action, returns the new state of the action (strings "true"/"false").

StelProperty operations (/api/stelproperty/)

GET operations

Implemented by StelPropertyService::getImpl

list

Lists all registered StelProperties, in the format

{
    <propId> : {
        value, //the current value of the StelProperty
        variantType, //the type string of the "value", as determined by QVariant::typeName
        typeString, //the type string of the StelProperty, as determined by QMetaProperty::typeName (may not be equal to "variantType")
        typeEnum, //the enum value of the type of the StelProperty, as determined by StelProperty::getType
    }
}

Note

The generic type conversions are done by QJsonValue::fromVariant

POST operations

Implemented by StelPropertyService::postImpl

set

Parameters: id (String) value (String)
Sets the StelProperty identified by id to the value value. The value is converted to the StelProperty type using QVariant logic, an error is returned if this is somehow not possible.

LocationService operations (/api/location/)

GET operations

Implemented by LocationService::getImpl

list

Returns the list of all stored location IDs (keys of StelLocationMgr::getAllMap) as JSON string array

countrylist

Returns the list of all known countries (StelLocaleMgr::getAllCountryNames), as a JSON array of objects of format

{
    name, //the english country name
    name_i18n //the localized country name (current language)
}

planetlist

Returns the list of all solar system planet names (SolarSystem::getAllPlanetEnglishNames), as a JSON array of objects of format

{
    name, //the english planet
    name_i18n //the localized planet name (current language)
}

planetimage

Parameters: planet (String)
Returns the planet texture image for the planet (english name)

POST operations

Implemented by LocationService::postImpl

setlocationfields

Parameters: id (String) | ( [latitude (Number)] [longitude (Number)] [altitude (Number)] [name (String)] [country (String)] [planet (String)] )
Changes and moves to a new location. If id is given, all other parameters are ignored, and a location is searched from the named locations using StelLocationMgr::locationForString with the id. Else, the other parameters change the specific field of the current StelLocation.

LocationSearchService operations (/api/locationsearch/)

GET operations

Implemented by LocationSearchService::getImpl

search

Parameters: term (String)
Searches the term in the list of predefined locations of the StelLocationMgr, and returns a JSON string array of the results.

nearby

Parameters: [planet (String)] [latitude (Number)] [longitude (Number)] [radius (Number)]
Searches near the location defined by planet, latitude and longitude for predefined locations (inside the given radius) using StelLocationMgr::pickLocationsNearby, returns a JSON string array.

ViewService operations (/api/view/)

GET operations

Implemented by ViewService::getImpl

listlandscape

Lists the installed landscapes as a JSON object of format

{
    <landscapeId> : <landscapeName>, //maps the landscape id to the translated landscape name
    ...
}

landscapedescription/

Note that the slash at the end is mandatory!
Provides virtual filesystem access to the current landscape directory. The operation can take a longer path in the URL. The remainder is used to access files in the landscape directory. If no longer path is given, the current HTML landscape description (as per LandscapeMgr::getCurrentLandscapeHtmlDescription) is returned. An example: landscapedescription/image.png returns image.png from the current landscape directory.

This operation allows to set up an HTML iframe or similar for the landscape description, including all images, etc. embedded in the HTML description.

listskyculture

Lists the installed sky cultures as a JSON object of format

{
    <skycultureId> : <skycultureName>, //maps the id to the translated name
    ...
}

skyculturedescription/

Note that the slash at the end is mandatory!
Provides virtual filesystem access to the current skyculture directory. The operation can take a longer path in the URL. The remainder is used to access files in the skyculture directory. If no longer path is given, the current HTML skyculture description (as per StelSkyCultureMgr::getCurrentSkyCultureHtmlDescription) is returned. An example: skyculturedescription/image.png returns image.png from the current skyculture directory.

This operation allows to set up an HTML iframe or similar for the skycultures description, including all images, etc. embedded in the HTML description.

listprojection

Lists the available projection types as a JSON object of format

{
    <projectionTypeKey> : <projectionName>, //maps the id to the translated name
    ...
}

projectiondescription

Returns the HTML description of the current projection (StelProjector::getHtmlSummary)