Skip to content
/
Create region

Create region

Request

Create a single region. The submitted geometries are unioned server-side into one MultiPolygon. Region names are unique across all organisations: a name clash returns 409 with the existing region's URL — there is no upsert, and regions cannot be replaced via the API. The creating application must be linked to an organisation (creation is attributed to it, and only that organisation can read the region afterwards) — otherwise 403. Linked region_groups must belong to your organisation.

Security
oauth2(Required scopes: region:write)
Headers
EvEnergy-Versionnumber

Specify the version of this endpoint to use.

Value:2
Bodyapplication/json
namestringrequired

Globally unique region name. A clash returns 409 region-name-conflict — there is no upsert on this endpoint.

typestring or null
Enum:"OTHER""ELECTRICITY"null
geometriesArray of any, [ 1 .. 1000 ] itemsrequired

One or more GeoJSON Polygon/MultiPolygon geometries. The server unions them (GEOS unary union, make_valid applied) into a single MultiPolygon.

region_groupsArray of strings, (uri)

URLs of existing region groups to link the new region to.

curl -i -X POST \
  https://developers.ev.energy/_mock/ev.energy-api-v2/regions \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'EvEnergy-Version: 2' \
  -d '{
    "name": "string",
    "type": "OTHER",
    "geometries": [
      {
        "type": "Polygon",
        "coordinates": [
          [
            [
              0,
              0
            ],
            [
              0,
              0
            ],
            [
              0,
              0
            ],
            [
              0,
              0
            ]
          ]
        ]
      }
    ],
    "region_groups": [
      "http://example.com"
    ]
  }'

Responses

Region created.

Headers
EvEnergy-Versionnumber

Indicates the version of the API that generated this response. If EvEnergy-Version was not specified in the request, this will be your OAuth application's default version.

Value:2
X-RateLimit-Limitnumber

The maximum number of requests that can be made to this endpoint per hour. Defaults to 1000 but may vary per client.

Default:1000
X-RateLimit-Remainingnumber

The number of requests remaining until this client's rate limit is reached.

Default:999
Bodyapplication/json
idstringregn[A-Z\d]{26}read-only
Example:"regn01JCK1HPNAANB8WN253G27SFPC"
urlstring, (uri)read-only
Example:"https://api.ev.energy/v2/regions/regn01JCK1HPNAANB8WN253G27SFPC"
namestring

Globally unique region name. Immutable after creation.

Example:"WEST ROXBURY"
typestring or null

Optional classification of the region.

Enum:"OTHER""ELECTRICITY"null
region_groupsArray of strings, (uri)read-only

URLs of the region groups this region belongs to.

created_atstring, (date-time)read-only
updated_atstring, (date-time)read-only
geometryGeoJsonMultiPolygon (object) or null
One of:

RFC 7946 GeoJSON MultiPolygon in WGS 84. Positions are [longitude, latitude]. Each member is a Polygon coordinate array.

Response
{
  "id": "regn01JCK1HPNAANB8WN253G27SFPC",
  "url": "https://api.ev.energy/v2/regions/regn01JCK1HPNAANB8WN253G27SFPC",
  "name": "WEST ROXBURY",
  "type": "OTHER",
  "region_groups": [
    "http://example.com"
  ],
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "geometry": {
    "type": "MultiPolygon",
    "coordinates": [ … ]
  }
}