{"id":51011128,"url":"https://github.com/tnc1997/dart-octopus-energy-api-client","last_synced_at":"2026-06-21T02:32:06.797Z","repository":{"id":322158015,"uuid":"1084559790","full_name":"tnc1997/dart-octopus-energy-api-client","owner":"tnc1997","description":"A client for accessing the Octopus Energy API. Please note that Client for Octopus Energy API is unofficial and not endorsed by Octopus Energy.","archived":false,"fork":false,"pushed_at":"2026-06-17T08:20:39.000Z","size":401,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-17T10:07:28.777Z","etag":null,"topics":["client","dart","octopus-energy-api"],"latest_commit_sha":null,"homepage":"https://pub.dev/packages/octopus_energy_api_client","language":"Dart","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tnc1997.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"buy_me_a_coffee":"tnc1997","ko_fi":"tnc1997"}},"created_at":"2025-10-27T21:02:47.000Z","updated_at":"2026-06-17T08:20:43.000Z","dependencies_parsed_at":null,"dependency_job_id":"c57907e0-a8a4-4267-b895-65eb807a5017","html_url":"https://github.com/tnc1997/dart-octopus-energy-api-client","commit_stats":null,"previous_names":["tnc1997/dart-octopus-energy-api-client"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/tnc1997/dart-octopus-energy-api-client","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tnc1997%2Fdart-octopus-energy-api-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tnc1997%2Fdart-octopus-energy-api-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tnc1997%2Fdart-octopus-energy-api-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tnc1997%2Fdart-octopus-energy-api-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tnc1997","download_url":"https://codeload.github.com/tnc1997/dart-octopus-energy-api-client/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tnc1997%2Fdart-octopus-energy-api-client/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34592050,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-21T02:00:05.568Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["client","dart","octopus-energy-api"],"created_at":"2026-06-21T02:32:06.654Z","updated_at":"2026-06-21T02:32:06.789Z","avatar_url":"https://github.com/tnc1997.png","language":"Dart","funding_links":["https://buymeacoffee.com/tnc1997","https://ko-fi.com/tnc1997"],"categories":[],"sub_categories":[],"readme":"# Client for Octopus Energy API\n\nA client for accessing the Octopus Energy API.\n\nPlease note that Client for Octopus Energy API is unofficial and not endorsed by Octopus Energy.\n\n## Installation\n\nAdd this package to your application.\n\n```shell\ndart pub add octopus_energy_api_client\n```\n\n## Getting Started\n\nMost applications target a single version of the Octopus Energy API. Import that\nversion's library (for example `v1.dart`) and you have everything you need — the\nclient, the services, the models, and the helpers — from one import.\n\n```dart\nimport 'package:octopus_energy_api_client/v1.dart';\n\nFuture\u003cvoid\u003e main() async {\n  // Your Octopus Energy API key.\n  final apiKey = 'sk_live_...';\n\n  // Obtain an HTTP client that authenticates every request with your API key.\n  final client = clientViaApiKey(apiKey);\n\n  // Create the API client for the v1 API.\n  final api = OctopusEnergyApiClient(client: client);\n\n  // Call an endpoint.\n  final account = await api.accounts.getAccount('A-1234ABCD');\n\n  // Release the underlying HTTP resources when you are done.\n  client.close();\n}\n```\n\nThat is all you need for everyday use. The rest of this document explains how the\npackage is organized and why — read on if you want to understand the imports or\nif you ever need to work with more than one API version at the same time.\n\n## Library Structure and Versioning\n\nThe Octopus Energy API is versioned (`/v1/…`, and newer `/v2/…` endpoints are\nbeginning to appear). A new API version is free to change the **shape** of its\ndata: a `v2` model called `Order` may have entirely different fields from a `v1`\n`Order`, and a service that exists in both versions may behave differently. If the\ntwo versions shared a single set of types, every such change would be a breaking,\ntangled mess.\n\nTo keep the versions cleanly separated, this package exposes **one importable\nlibrary per API version**, plus a small common library for the pieces that never\nchange between versions. You choose which version(s) to import, and Dart's\n`import ... as` prefixes keep them from colliding.\n\n### Import Entry Points\n\n| Import                                                             | What it contains                                                                                                                                                                                     |\n|--------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `package:octopus_energy_api_client/octopus_energy_api_client.dart` | **Common infrastructure only.** Version-independent plumbing: `clientViaApiKey`, the exception type, and the API host constant. It contains **no models and no client** — those belong to a version. |\n| `package:octopus_energy_api_client/v1.dart`                        | **The complete v1 SDK.** The v1 `OctopusEnergyApiClient`, every v1 service, and every v1 model and enum — plus a re-export of the common infrastructure above, so a single import is enough.         |\n| `package:octopus_energy_api_client/v2.dart`                        | **The complete v2 SDK** (planned). The same shape as `v1.dart`, for the v2 API.                                                                                                                      |\n\nEverything under `lib/src/` is private implementation detail; only the libraries\nabove are part of the public API.\n\n### Using a Single Version\n\nImport the version's library directly and use everything unprefixed, exactly as in\n[Getting Started](#getting-started):\n\n```dart\nimport 'package:octopus_energy_api_client/v1.dart';\n\nfinal api = OctopusEnergyApiClient(client: clientViaApiKey(apiKey));\n\nfinal products = await api.products.listProducts();\nfinal product = await api.products.retrieveProduct('VAR-22-11-01');\nfinal meterPoint = await api.electricityMeterPoints.getElectricityMeterPoint('1234567890123');\n```\n\n### Using More Than One Version\n\nWhen you need two API versions in the same file, import each version's library with\na prefix and import the common infrastructure once, unprefixed:\n\n```dart\nimport 'package:octopus_energy_api_client/octopus_energy_api_client.dart';\nimport 'package:octopus_energy_api_client/v1.dart' as v1;\nimport 'package:octopus_energy_api_client/v2.dart' as v2; // illustrative\n\nFuture\u003cvoid\u003e main() async {\n  // One authenticated HTTP client, shared by every version's API client.\n  final client = clientViaApiKey('sk_live_...');\n\n  final v1Api = v1.OctopusEnergyApiClient(client: client);\n  final v2Api = v2.OctopusEnergyApiClient(client: client); // illustrative\n\n  final account = await v1Api.accounts.getAccount('A-1234ABCD');\n  final order = await v2Api.orders.getOrder('...'); // illustrative\n\n  client.close();\n}\n```\n\nThe `v1.` / `v2.` prefix is the single mechanism that resolves any name clash\nbetween versions — whether it is the client, a service, or a model. Because the\nprefix already carries the version, **the type names themselves are deliberately\nnot version-suffixed**: it is `v1.OctopusEnergyApiClient` and\n`v2.OctopusEnergyApiClient`, not `OctopusEnergyApiV1Client`. This mirrors the\napproach used by Google's official [`googleapis`](https://pub.dev/packages/googleapis)\npackage (e.g. `package:googleapis/calendar/v3.dart` exposes a `CalendarApi`, with\nthe version in the import path rather than the class name).\n\nSome consequences worth knowing:\n\n- **Each version has its own client.** There is no single object that spans\n  versions; you create one `OctopusEnergyApiClient` per version. Pass them the same\n  `http.Client` (as above) so authentication and connection pooling are shared.\n- **The common library carries no client.** Importing\n  `package:octopus_energy_api_client/octopus_energy_api_client.dart` on its own gives\n  you `clientViaApiKey` and the exception type, but not a client — that is\n  intentional. Reach for a version library (`v1.dart`) to get a client.\n- **`clientViaApiKey` lives in the common library** and is re-exported by every\n  version library, so `clientViaApiKey`, `v1.clientViaApiKey`, and\n  `v2.clientViaApiKey` all refer to the same helper.\n\n## Authentication\n\n`clientViaApiKey` returns an `http.Client` that attaches your API key to every\nrequest:\n\n```dart\nfinal client = clientViaApiKey('sk_live_...');\n```\n\nYou can pass any `http.Client` to `OctopusEnergyApiClient(client: ...)`, so you are\nfree to wrap or substitute it — for example, to add logging, retries, or a mock\nclient in tests. Remember to `close()` the HTTP client when you are finished.\n\n## Errors\n\nUnsuccessful responses throw an `OctopusEnergyApiClientException`, which is\navailable from both the common library and every version library:\n\n```dart\ntry {\n  await api.accounts.getAccount('A-1234ABCD');\n} on OctopusEnergyApiClientException catch (e) {\n  print('Request failed: $e');\n}\n```\n\n## Services\n\nThe v1 `OctopusEnergyApiClient` exposes the following services. Each is created\nlazily on first access and reuses the client's `http.Client`.\n\n| Service                  | Accessor                     | Example methods                                                                                               |\n|--------------------------|------------------------------|---------------------------------------------------------------------------------------------------------------|\n| Accounts                 | `api.accounts`               | `getAccount`, `createAccount`, `renewBusinessTariff`                                                          |\n| Electricity meter points | `api.electricityMeterPoints` | `getElectricityMeterPoint`, `listElectricityMeterConsumption`                                                 |\n| Gas meter points         | `api.gasMeterPoints`         | `listGasMeterConsumption`                                                                                     |\n| Industry                 | `api.industry`               | `listIndustryGridSupplyPoints`                                                                                |\n| IVR support              | `api.ivrSupport`             | `minimalTwilioEnqueue`                                                                                        |\n| Products                 | `api.products`               | `listProducts`, `retrieveProduct`, `listElectricityTariffStandardUnitRates`, `listGasTariffStandardUnitRates` |\n| Quotes                   | `api.quotes`                 | `createQuote`, `shareQuoteViaEmail`                                                                           |\n| Voice                    | `api.voice`                  | `twilioEnqueueAudio`                                                                                          |\n\n## Models\n\nModel fields mirror what the API **actually returns**, which is not always what\nthe published schema declares. Two consequences worth knowing as a consumer:\n\n- **Nullability.** A single model can serve both a request body and a response\n  body, and responses routinely omit fields the request requires. Response fields\n  are therefore typed as nullable wherever the API may omit them — so treat a\n  nullable field as genuinely optional and null-check it, even if the official\n  schema lists it as `required`.\n- **Numeric types.** Some numeric values the schema declares as strings are\n  returned as JSON numbers (for example `Consumption.consumption`, and the\n  `Installation` capacity/generation figures). Their `fromJson` accepts either\n  form, so you do not need to handle the wire-type difference yourself.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftnc1997%2Fdart-octopus-energy-api-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftnc1997%2Fdart-octopus-energy-api-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftnc1997%2Fdart-octopus-energy-api-client/lists"}