> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flatpeak.com/llms.txt
> Use this file to discover all available pages before exploring further.
# List locations
> Location is an identifier of a supply address.
Returns list of all Locations.
The objects are returned sorted by creation date, with the most recent appearing first. If no parameters are specified in the request, all objects in pages of 30 are returned.
## OpenAPI
````yaml api-reference/zero/flatpeak-api-spec-zero.json GET /locations
openapi: 3.0.3
info:
description: Flatpeak API
version: 2024-08-24.zero
title: Flatpeak API
termsOfService: https://flatpeak.com/legal
contact:
name: Technical Support
email: support@flatpeak.com
url: https://flatpeak.com/contact
license:
name: Apache 2.0
url: https://flatpeak.com/legal
servers:
- url: https://api.flatpeak.com
description: Location
security: []
tags:
- name: Consumption
description: Consumption operations
- name: Customers
description: Customer operations
- name: Devices
description: Device operations
- name: Meters
description: Meter readings operations
- name: Events
description: Events operations
- name: Login
description: Bearer auth token operations
- name: Connect
description: Connect operations
- name: Locations
description: Location operations
- name: Rates
description: Rates operations
- name: Costs
description: Consumption cost calculations
- name: Schedules
description: Consumption schedules
- name: Tariffs
description: Tariff operations
- name: Slots
description: Slots operations
externalDocs:
description: Location documentation
url: https://docs.flatpeak.com
paths:
/locations:
parameters: []
get:
tags:
- Locations
summary: List locations
description: >-
Location is an identifier of a supply address.
Returns list of all Locations.
The objects are returned sorted by creation date, with the most recent
appearing first. If no parameters are specified in the request, all
objects in pages of 30 are returned.
operationId: list-locations
parameters:
- $ref: '#/components/parameters/reference_id'
- $ref: '#/components/parameters/customer_id'
- $ref: '#/components/parameters/starting_after'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/ending_before'
responses:
'200':
$ref: '#/components/responses/LocationNewList'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
'500':
$ref: '#/components/responses/500'
security:
- bearerAuth: []
components:
parameters:
reference_id:
name: reference_id
in: query
required: false
schema:
type: string
description: >-
A reference that is meaningful to you, for example, an ID from your
system.
customer_id:
name: customer_id
in: query
schema:
type: string
example: cus_65e421d1daa4a24082b4f590
description: Flatpeak `customer_id`.
starting_after:
schema:
type: string
in: query
name: starting_after
description: >-
Specifies a cursor for pagination use; provider_id defines the place in
the list. To retrieve the next page in the list include starting_after
where ID is the last ID in the currently retrieved list.
limit:
schema:
type: integer
in: query
name: limit
description: >-
A limit on the number of objects to be returned. Can range between 1 and
100, and the default is 30.
ending_before:
schema:
type: string
in: query
name: ending_before
description: >-
Specifies a cursor for pagination use; provider_id defines the place in
the list. To retrieve the previous page in the list, include
ending_before, which is the first ID in the currently retrieved list.
responses:
'403':
description: 403 bad credentials
content:
application/json:
schema:
type: object
x-examples:
Example:
message: Bad credentials
properties:
message:
type: string
example: Bad credentials
examples: {}
'404':
description: 404 response
content:
application/json:
schema:
type: object
x-examples:
Example:
message: Not Found
properties:
message:
type: string
example: Not Found
examples: {}
'500':
description: 500 error
content:
application/json:
schema:
type: object
x-examples:
'':
message: Internal Server Error
properties:
message:
type: string
example: Internal Server Error
examples: {}
LocationNewList:
description: Example response
content:
application/json:
schema:
type: object
properties:
object:
type: string
x-stoplight:
id: bg1p9v02lpgo7
description: Represents the object’s type. i.e. `list`.
example: list
url:
type: string
x-stoplight:
id: m91a6y1hctjkr
description: Represents the URL slug for the object.
example: /locations
has_more:
type: boolean
x-stoplight:
id: zn0jxuw4gplgr
description: Is set to `true` if more objects are available.
data:
type: array
x-stoplight:
id: bitma8en99j8b
items:
$ref: '#/components/schemas/LocationNew'
required:
- object
- url
- has_more
- data
schemas:
LocationNew:
type: object
x-stoplight:
id: uwi9ovzib5jb4
x-examples: {}
title: LocationNew
description: This object represents a supply address.
x-tags:
- Locations
properties:
id:
type: string
description: Flatpeak unique location ID
example: loc_641b90b758fb8e6293716e40
object:
type: string
description: Represents the object’s type. I.e. `location`.
example: location
live_mode:
type: boolean
description: >-
Has the value `true` if the object exists in live mode or the value
false if the object exists in test mode.
reference_id:
type: string
description: >-
A reference that is meaningful to you, for example, an ID from your
system.
x-stoplight:
id: uhvd1tt1iqabo
example: LOC1234567890
customer_id:
type: string
description: Flatpeak customer ID.
x-stoplight:
id: uhvd1tt1iqabo
example: cus_65e421d1daa4a24082b4f590
timezone:
type: string
description: >-
The timezone at the location, in 'tz database format'. I.e.
'Europe/Berlin'.
x-stoplight:
id: aov8uxt6289sn
example: Europe/London
currency_code:
type: string
description: Currency at the location in ISO 4217.
example: EUR
x-stoplight:
id: yjl56bkyw8d0f
grid_node_id:
type: string
description: >-
Utility provided identifier for the grid segment (e.g. circuit or
feeder), used for location specific pricing and signals.
Note, this parameter is in preview and not generally available.
Contact support@flatpeak.com to enable it.
example: '01459223'
x-stoplight:
id: yjl56bkyw8d0f
postal_address:
$ref: '#/components/schemas/PostalAddress'
geo_location:
$ref: '#/components/schemas/GeoLocation'
tariff_status:
type: object
x-stoplight:
id: lwkb7g1qkapai
description: Health status of tariff elements.
properties:
commodity_import:
type: string
x-stoplight:
id: rr06lr4th2f4n
example: CONNECTED
description: Status of all COMMODITY/IMPORT tariff elements.
commodity_export:
type: string
x-stoplight:
id: ggpckds4cj8k4
example: ERROR
description: Status of all COMMODITY/EXPORT tariff elements.
non_commodity_import:
type: string
x-stoplight:
id: 6aqyxvmgkg8hc
example: NOT_CONNECTED
description: Status of all NON_COMMODITY/IMPORT tariff elements.
non_commodity_export:
type: string
x-stoplight:
id: 5jhzcx06kppe3
description: Status of all NON_COMMODITY/EXPORT tariff elements.
example: NOT_SUPPORTED
local:
type: string
x-stoplight:
id: wwywg3mzpqu7e
description: Status of LOCAL tariff element.
example: NOT_SUPPORTED
tariff_elements:
type: array
x-stoplight:
id: xzt6lreurtp2g
description: >-
An array of tariff IDs that apply to this location. To manage
tariffs for a location, use the tariffs-elements endpoint. NOTE:
This field is in beta and is not currently generally supported.
Check back in early September 2024.
items:
x-stoplight:
id: ed96ubaxsrght
type: string
example: trf_66ba584eb6923d7c3b942ef6
time_created:
type: string
description: Time when the object was created, in UTC.
format: date-time
account_id:
type: string
x-stoplight:
id: wg4bogwpe8daf
example: acc_661677911f2197045e6cf1b1
description: Flatpeak account ID.
required:
- id
- object
- live_mode
- time_created
- account_id
PostalAddress:
title: PostalAddress
x-stoplight:
id: c08e007sm4dhc
type: object
description: Information on the postal address.
x-examples: {}
properties:
address_line1:
type: string
x-stoplight:
id: y3w1smzzi7doq
description: Address line 1 (e.g., street, PO Box, or company name).
example: 1-3
address_line2:
type: string
x-stoplight:
id: d2a0gmwulev18
description: Address line 2 (e.g., apartment, suite, unit, or building).
example: Strand
city:
type: string
x-stoplight:
id: 6vwq2lw863yc5
description: City, district, suburb, town, or village.
example: London
state:
type: string
x-stoplight:
id: yjtu3ijseco94
example: NSW
description: >-
State, county, province, or region. For
[Australia](https://en.wikipedia.org/wiki/ISO_3166-2:AU),
[Canada](https://en.wikipedia.org/wiki/ISO_3166-2:CA), and
[US](https://en.wikipedia.org/wiki/ISO_3166-2:US), use ISO 3166-2
state or province abbreviations (codes).
post_code:
type: string
x-stoplight:
id: 1styvjbg8556w
description: ZIP or postal code.
example: WC2N 5EH
country_code:
type: string
x-stoplight:
id: 53dqxz94xzzys
description: >-
Two-letter country code in [ISO 3166-1
alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).
example: GB
GeoLocation:
title: GeoLocation
x-stoplight:
id: 5g5zsf24cp9v3
type: object
x-examples: {}
description: >-
Latitude and longitude of the location. Flatpeak resolves this
automatically using the `postal_address` that you provide. This
information is used to determine market price and carbon regions.
properties:
lat:
x-stoplight:
id: reqfsofuowtmf
type: number
example: 50.12345
lng:
type: number
x-stoplight:
id: za32cq461xz6a
example: -1.23456
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >-
Authenticate with `bearer_token` you obtained from
[/login](/api-reference/zero/login/create-a-bearer-token) endpoint.
````