Sites

List Sites

Retrieves a paginated list of sites.

Endpoint: GET /sites

Authentication: Required (API Key)

Query Parameters

Parameter	Type	Required	Description
`id`	integer[]	No	Filter sites by one or more site IDs.
`_page`	integer	No	Page number (positive integer, defaults to 1)
`_pageSize`	integer	No	Number of items per page (positive integer, max varies by configuration)
`_sortBy`	string	No	Sort order. Format: `+field` for ascending or `-field` for descending.

Response Format

Returns a paginated response with the following structure:

{
    "data": [
        {
            "id": "integer",
            "company_id": "integer",
            "name": "string",
            "type": "string",
            "stage": "string",
            "coordinates": {
                "type": "Point",
                "coordinates": ["number", "number"]
            } | null,
            "geo_area": "number",
            "peak_power": "number | null",
            "ac_power": "number | null",
            "address_line1": "string | null",
            "address_line2": "string | null",
            "address_line3": "string | null"
        }
    ],
    "pagination": {
        "page": "integer",
        "pageSize": "integer",
        "rowCount": "integer",
        "pageCount": "integer"
    }
}

Response Fields

Every site in data contains all of the fields below. Fields that have no value are returned as null; they are never omitted.

id: Integer ID of the site
company_id: Integer ID of the company that owns the site
name: Name of the site
type: Site type, one of SOLAR, GENERIC, AGRICULTURE, WIND, HYDRO, STORAGE, CHARGING, ROAD. Never null
stage: Site stage, one of PLANNING, CONSTRUCTION, OPERATION. Never null
coordinates: GeoJSON Point at the centroid of the site boundary. The coordinates array is [longitude, latitude] (WGS 84), longitude first as GeoJSON requires. null when the site boundary is empty
geo_area: Area of the site boundary in square metres (m²). 0 when the site boundary is empty
peak_power: Peak power of the site in megawatt-peak (MWp). null when not set
ac_power: AC power of the site in megavolt-ampere (MVA). null when not set
address_line1, address_line2, address_line3: Address lines of the site. null when not set

Example Requests

List all sites:

curl -X GET "https://api.sitemark.com/sites?_page=1&_pageSize=25" \
  -H "Authorization: ApiKey your-api-key-here"

Filter by single site ID:

curl -X GET "https://api.sitemark.com/sites?id=1234&_page=1&_pageSize=25" \
  -H "Authorization: ApiKey your-api-key-here"

Filter by multiple site IDs (without brackets):

curl -X GET "https://api.sitemark.com/sites?id=1234&id=1235&_page=1&_pageSize=25" \
  -H "Authorization: ApiKey your-api-key-here"

Filter by multiple site IDs (with brackets):

curl -g -X GET "https://api.sitemark.com/sites?id[]=1234&id[]=1235&_page=1&_pageSize=25" \
  -H "Authorization: ApiKey your-api-key-here"

Example Response

{
    "data": [
        {
            "id": 1234,
            "company_id": 5678,
            "name": "Downtown Construction Site",
            "type": "SOLAR",
            "stage": "CONSTRUCTION",
            "coordinates": {
                "type": "Point",
                "coordinates": [4.3517, 50.8503]
            },
            "geo_area": 452310.75,
            "peak_power": 12.5,
            "ac_power": 10,
            "address_line1": "Rue de la Loi 16",
            "address_line2": null,
            "address_line3": "1000 Brussels"
        },
        {
            "id": 1235,
            "company_id": 5678,
            "name": "Industrial Park Development",
            "type": "GENERIC",
            "stage": "PLANNING",
            "coordinates": {
                "type": "Point",
                "coordinates": [5.5796, 50.6326]
            },
            "geo_area": 128004.2,
            "peak_power": null,
            "ac_power": null,
            "address_line1": null,
            "address_line2": null,
            "address_line3": null
        }
    ],
    "pagination": {
        "page": 1,
        "pageSize": 25,
        "rowCount": 2,
        "pageCount": 1
    }
}

Error Responses

Status Code	Description
401	Unauthorized - Invalid or missing API key
400	Bad Request - Invalid query parameters
429	Too Many Requests - A rate limit was exceeded
500	Internal Server Error

Create Site

Creates a site. The site is set up exactly as one created in the Sitemark web app.

Endpoint: POST /sites

Authentication: Required (API Key with the SITE_CREATE permission)

Body Parameters

Parameter	Type	Required	Description
`name`	string	Yes	Name of the site
`geo_boundaries`	object	Yes	A bare GeoJSON `Polygon` or `MultiPolygon` geometry, in WGS 84 (longitude, latitude), 2D only. Not a `Feature` — see Boundary format
`type`	string	Yes	One of `SOLAR`, `WIND`, `HYDRO`, `AGRICULTURE`, `GENERIC`, `STORAGE`, `CHARGING`, `ROAD`
`properties.PEAK_POWER`	number	For `SOLAR`, `WIND`, `HYDRO`	Peak power of the site in megawatt-peak (MWp). Must be greater than 0
`properties.AGRICULTURE_APPLICATION`	string	For `AGRICULTURE`	The crop grown on the site. One of `SUGAR_BEET`, `WHEAT`, `BARLEY`, `MAIZE`, `RICE`, `SUNFLOWER`, `TOMATO`, `CANOLA`, `PEAR`, `APPLE`, `STRAWBERRY`, `MIXED`
`properties.CURRENCY`	string	No	Defaults to `USD` for companies in the US and `EUR` everywhere else
`properties.*`	mixed	No	Any other site property. The keys match the fields in the site settings panel in the web app; the most common are `AC_POWER`, `COMMISSIONING_DATE`, `NUMBER_OF_PANELS` and `CONSTRUCTION_TYPE`. An unknown key is rejected with an error naming the key
`company_id`	integer	No	Defaults to the API key’s own company. Naming another company requires permission to create sites there
`stage`	string	No	One of `PLANNING`, `CONSTRUCTION`, `OPERATION`. Defaults to `PLANNING`
`unit_system`	string	No	One of `metric`, `imperial`, `us-survey-imperial`
`epsg`	integer	No	EPSG code of the site’s coordinate system, e.g. `32631` (WGS 84 / UTM zone 31N). Defaults to `4326`. An unsupported code is rejected
`instructions`	string	No	Free-text instructions for the site
`address_line1`–`address_line3`	string	No	Address lines of the site
`contact_name`	string	No	Name of the site contact
`contact_phone`	string	No	Phone number of the site contact
`contact_mail`	string	No	Email address of the site contact

Boundary format

geo_boundaries takes the geometry itself, not a GeoJSON Feature or FeatureCollection. Most GIS tools (QGIS, or a KML converted to GeoJSON) export Features: send the Feature’s geometry member. A Feature is rejected with an error that says so.

"geo_boundaries": {
    "type": "Polygon",
    "coordinates": [[[4.35, 50.85], [4.36, 50.85], [4.36, 50.86], [4.35, 50.85]]]
}

Coordinates must be 2D (longitude, latitude): a position with an altitude is rejected. The boundary must be a valid polygon: a ring that crosses itself (a “bow tie”) is rejected, and the error says where.

Other validation

A property key inside properties that the endpoint does not know is rejected and named in the error. A top-level field it does not know is ignored rather than rejected — check the spelling of optional top-level fields, as a typo there is silently dropped.

Licences are not part of this endpoint — a site created here has none, and they are activated separately.

Who can see the new site

The API key that created the site always has access to it, and so does every user with the Can access all sites in the portfolio permission. Users who only have access to specific sites do not see the new site until it is shared with them, or with a group they belong to, in the Sitemark web app — the same as for a site someone else creates there.

Response Fields

Responds with 201 Created and the new site, with every field a site has in the List Sites response — id, company_id, name, type, stage (PLANNING when not given), coordinates, geo_area, peak_power, ac_power and the address lines — plus the settings below. The boundary you sent is not echoed back.

epsg: EPSG code of the site’s coordinate system. 4326 when not given
unit_system: Unit system of the site. Derived from the coordinate system and the site’s location when not given
properties: The site properties, including the defaulted CURRENCY

Example Request

curl -X POST "https://api.sitemark.com/sites" \
  -H "Authorization: ApiKey your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "Solar Park North",
        "type": "SOLAR",
        "geo_boundaries": {
            "type": "Polygon",
            "coordinates": [[[4.35, 50.85], [4.36, 50.85], [4.36, 50.86], [4.35, 50.85]]]
        },
        "properties": { "PEAK_POWER": 12.5 }
      }'

Example Response

{
    "id": 1236,
    "company_id": 5678,
    "name": "Solar Park North",
    "type": "SOLAR",
    "stage": "PLANNING",
    "coordinates": {
        "type": "Point",
        "coordinates": [4.3533, 50.8533]
    },
    "geo_area": 393612.4,
    "peak_power": 12.5,
    "ac_power": null,
    "address_line1": null,
    "address_line2": null,
    "address_line3": null,
    "epsg": 4326,
    "unit_system": "metric",
    "properties": {
        "PEAK_POWER": 12.5,
        "CURRENCY": "EUR"
    }
}

Error Responses

Status Code	Description
401	Unauthorized - Invalid or missing API key
400	Bad Request - The message names the fields that are wrong and the values they accept
403	Forbidden - The API key may not create sites for this company, or the company does not exist
429	Too Many Requests - A rate limit was exceeded
500	Internal Server Error