SolarUser Location Request API

The SolarUser Location Request API provides methods to manage requests for new location datum sources. Location sources are used for things like weather and market price datum streams, but must be created by SolarNetwork administrators. Using the Location Request API you can submit requests for new location sources to be created, and monitor the status of those requests. Once a location request has been processed, SolarNode devices can be configured to post datum to the associated location datum sources.

Endpoints

Verb	Endpoint	Description
POST	/location/meta/request	Submit a location request.
GET	/location/meta/request	List previously submitted location requests.
GET	/location/meta/request/{id}	Get a specific location request.
POST	/location/meta/request/{id}	Update a location request.
DELETE	/location/meta/request/{id}	Delete a location request.

Date formatting

For endpoints that return timestamp values (full date and time) the timestamps will be rendered as string values using the ISO 8601 timestamp format YYYY-MM-dd'T'HH:mm:ss.SSSSSS'Z' in the UTC time zone, for example 2020-03-01T10:30:49.346827Z. The fractional second can contain up to 6 digits for nanosecond level precision, and will only display up to the precision set in the timestamp. That means the fractional seconds might not appear if the timestamp has no fractional seconds.

Location request data

Each location request encapsulates the location information submitted into an object with the following properties:

Property	Type	Description
sourceId	string	The source ID of the location source, or base source ID if multiple location sources will be created.
features	array<string>	An array of desired location features.
location	object	A location details object.

Here is an example object in JSON:

{
  "sourceId": "OpenWeatherMap",
  "features": ["weather", "day", "forecast"],
  "location": {
    "country":         "NZ",
    "zone":            "Pacific/Auckland",
    "stateOrProvince": "Wellington",
    "locality":        "Wellington City",
    "name":            "Windy Wellington"
  }
}

Location features

Location requests include a set of feature names to indicate the desired purpose of the request. A request should include all the features desired. The supported feature names are:

Feature	Description
day	Day-related information such as sunrise, sunset, etc.
forecast	Weather forecast information.
price	Pricing information.
weather	Weather observation information.

Location details

Each location request has an associated details object that describes the location. The details object supports the following properties:

Property	Type	Description
name	string	(Required) A general display name for the location. A good option is using the locality, possibly along with the state/province abbreviation.
country	string	(Required) An ISO 3166 2-character country code, for example NZ, US.
zone	string	(Required) A full tz database time zone, for example Pacific/Auckland, America/New_York.
region	string	A region name.
stateOrProvince	string	A state or province name.
postalCode	string	A postal code.
locality	string	A locality (city) name.
street†	string	A street address.
lat†	decimal	GPS latitude.
lon†	decimal	GPS longitude.
el†	decimal	GPS elevation (meters).

† Location details more specific than locality are usually not appropriate for public location details and should not be included.

Location request entity

A location request entity represents a submitted location request request. It contains the following properties:

Property	Type	Description
id	number	A unique identifier assigned by SolarNetwork.
created	string	The date the request was created.
modified	string	The date the request was last modified.
userId	number	The ID of the user that submitted the request.
status	Location Request Status	The status of the request.
data	Location Request Data	The request information.

Location request status

Each request has a status that will be updated once the request has been processed by SolarNetwork administrators. The possible status values are:

Status	Description
Submitted	The request has been submitted but not yet processed.
Rejected	The request has been rejected. The message property of the request will indicate a reason for the rejection.
Duplicate	The request is a duplicate of an existing location. The locationId of the request will indicate the existing location ID.
Created	The location has been created. The locationId of the request will indicate the ID of the new location.

Location request add

Add a new location request. Use the Location request list endpoint to view all submitted requests.

POST	/solaruser/api/v1/sec/location/meta/request

The request must be submitted as application/json with a Location Request Data JSON object.

Here is an example for an OpenWeatherMap location request:

{
  "sourceId": "OpenWeatherMap",
  "features": ["weather", "day", "forecast"],
  "location": {
    "country":         "NZ",
    "zone":            "Pacific/Auckland",
    "stateOrProvince": "Wellington",
    "locality":        "Wellington City",
    "name":            "Windy Wellington"
  }
}

Location request add response

The response will be Location Request Entity object.

Location request list

List the available location requests previously submitted via the Location request add endpoint.

GET	/solaruser/api/v1/sec/location/meta/request
requestStatuses	A comma-delimited list of status values to limit the results to. If multiple values are specified, any matching status is included.
location.name	A general name to match. This term will be used to match against the country, region, state, locality, and postal code values of the location details.

Location request list response

The response contains a list of location request entities objects.

An example response looks like:

{
  "success": true,
  "data": {
    "totalResults": 1,
    "startingOffset": 0,
    "returnedResultCount": 1,
    "results": [
      {
        "id": 1,
        "created": "2022-05-20 03:51:42.380936Z",
        "modified": "2022-05-20 03:51:42.380936Z",
        "userId": 1,
        "status": "Submitted",
        "data": {
          "features": [
            "weather",
            "forecast",
            "day"
          ],
          "location": {
            "name": "Wellington",
            "country": "NZ",
            "locality": "Wellington City",
            "timeZoneId": "Pacific/Auckland",
            "stateOrProvince": "Wellington"
          },
          "sourceId": "OpenWeatherMap"
        }
      }
    ]
  }
}

Location request view

View a request previously submitted via the Location request add endpoint.

GET	/solaruser/api/v1/sec/location/meta/request/{id}
id	The ID of the request.

Location request view response

The response is a location request entities object. For example:

{
  "success": true,
  "data": {
    "id": 1,
    "created": "2022-05-19 23:16:28.486141Z",
    "modified": "2022-05-19 23:16:28.486141Z",
    "userId": 1,
    "status": "Submitted",
    "data": {
      "location": {
        "name": "Wellington",
        "country": "NZ",
        "locality": "Wellington City",
        "timeZoneId": "Pacific/Auckland",
        "stateOrProvince": "Wellington"
      },
      "sourceId": "OpenWeatherMap"
    }
  }
}

Location request update

Update a request previously submitted via the Location request add endpoint. Only requests in the Submitted status may be updated.

POST	/solaruser/api/v1/sec/location/meta/request/{id}
id	The ID of the request to update.

The request must be submitted as application/json with a Location Request Data JSON object (the same format as used in the Location request add endpoint).

Location request update response

The response is the updated location request entities object.

Location request delete

Delete a request previously submitted via the Location request add endpoint. Only requests in the Submitted status may be deleted.

DELETE	/solaruser/api/v1/sec/location/meta/request/{id}
id	The ID of the request to delete.

Location request delete response

The response is empty for this endpoint.