SolarUser Location Request API - SolarNetwork/solarnetwork GitHub Wiki

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.

Add a custom footer
⚠️ **GitHub.com Fallback** ⚠️