Endpoints and features
All of the following schema is available through our GraphQL tool, which offers autocomplete on fields too.
List passports
How to use
query {
listPassportInstance(
sorting: { key: MODEL, direction: ASC }
pagination: { page: 1, size: 20 }
filter: {
category: EV
status: ORIGINAL
typeFilter: BOTH
stateFilter: BOTH
}
) {
id
general {
name
category
}
}
}
Get one passport
How to use
{
getPassportInstance(id: "pass12345") {
id
dataSource {
name
instanceUrl
}
}
}
Create passport
Info
You can generate dynamic data for creating a passport through the following link:
https://provider-<provider-name>.dev.thebatterypass.io/api/generate/internal
How to use
mutation {
createPassportInstance(
passport: {
id: "did:web:provider-<provider-name>.dev.thebatterypass.io:passport-instances:1d9b185e-71f3-4baa" # Note: the ID must change for every passport. Please just change some random numbers at the end of this example you have.
isComplete: true
isModel: false
carbonFootprint: {
amount: 87
blockchainVerification: FULL
description: "Description for Carbon Footprint"
lastUpdated: "2023-09-21T21:14:25"
lastUpdatedBy: "V-Guard Auditor"
performanceClass: "C"
sharePerStage: [
{ amount: 72, stage: RAW_MATERIAL_EXTRACTION }
{ amount: 13, stage: MAIN_PRODUCTION }
{ amount: 1, stage: DISTRIBUTION }
{ amount: 1, stage: RECYCLING }
]
study: "https://vguard.com/studies/articles/abs/78597"
title: "Carbon Footprint"
}
circularity: {
blockchainVerification: FULL
description: "Description for Circularity"
dismantlingDocumentation: [
{
document: "https://vguard.com/technical-documentation.pdf"
documentType: OTHER_MANUAL
mimeType: "application/pdf"
}
{
document: "https://vguard.com/dismantling-manual.pdf"
documentType: DISMANTLING_MANUAL
mimeType: "application/pdf"
}
{
document: "https://vguard.com/application-removal-manual.pdf"
documentType: REMOVAL_MANUAL
mimeType: "application/pdf"
}
{
document: "https://vguard.com/library/electric-vehicle-battery-model"
documentType: MODEL_3_D
mimeType: "application/javascript"
}
{
document: "https://vguard.com/invoices/bill-33314.pdf"
documentType: BILL_OF_MATERIAL
mimeType: "application/pdf"
}
{
document: "https://vguard.com/figure/example-of-a-basic-battery-pack-design-fig-30283"
documentType: DRAWING
mimeType: "text/html"
}
]
endOfLifeInformation: {
informationOnCollection: "Return battery to collection point or dealer"
separateCollection: "Ensure that the waste battery is disposed of according to material composition"
wastePrevention: "Don't dispose battery at normal waste"
}
lastUpdated: "2023-10-26T05:15:15"
lastUpdatedBy: "V-Guard Auditor"
recycledContent: [
{ material: NICKEL, postConsumerShare: 8, preConsumerShare: 12 }
{ material: COBALT, postConsumerShare: 3, preConsumerShare: 1 }
{ material: LITHIUM, postConsumerShare: 9, preConsumerShare: 12 }
{ material: LEAD, postConsumerShare: 3, preConsumerShare: 17 }
]
renewableContent: 8
safetyRequirements: {
extinguishingAgents: ["Use dry chemical extinguisher"]
safetyInstructions: "Store in cool and dry area"
}
sparePartsSources: [
{
address: {
country: "Madagascar"
street: "91189 Geovany Heights"
zipCode: "04116-4098"
}
components: [
{ partName: "Cell", partNumber: "C01081039" }
{ partName: "Module", partNumber: "M12994281" }
{ partName: "Pack", partNumber: "P26216704" }
{ partName: "BMS", partNumber: "B60737981" }
]
email: "contact@vguard.com"
name: "V-Guard Auditor"
webAddress: "https://vguard.com"
}
]
title: "Circularity"
}
compliance: {
blockchainVerification: UNVERIFIED
conformity: "https://vguard.com/conformity.pdf"
description: "Description for Compliance"
euDeclarationOfConformityId: "CE-79479"
lastUpdated: "2024-07-30T18:16:40"
lastUpdatedBy: "V-Guard Auditor"
materialSymbols: [
{
description: {
deDe: "https://vguard.com"
enGb: "https://vguard.com"
}
symbolUri: "https://vguard.com"
}
]
separateCollection: {
description: {
deDe: "https://vguard.com"
enGb: "https://vguard.com"
}
symbolUri: "https://vguard.com"
}
testReport: "https://vguard.com/report.pdf"
title: "Compliance"
}
general: {
blockchainVerification: FULL
category: EV
description: "Description for General"
lastUpdated: "2024-06-15T13:16:58"
lastUpdatedBy: "V-Guard Auditor"
manufacturedDate: "2023-11-30T15:34:40"
manufacturer: {
brand: "V-Guard"
id: "V-Guard Auditor"
name: "V-Guard Auditor"
}
manufacturingPlace: {
country: "Central African Republic"
street: "126 Grant Light"
zipCode: "96145"
}
model: "M-388544923388"
name: "B-168998"
operator: {
brand: "V-Guard"
id: "V-Guard Auditor"
name: "V-Guard Auditor"
uri: "https://vguard.com"
}
serial: "686187114581126"
status: ORIGINAL
title: "General"
weight: 400.832
}
materialComposition: {
blockchainVerification: FULL
chemistry: { longName: "Lithium Cobalt Oxide", shortName: "LCO" }
criticalRawMaterials: [NICKEL, COBALT, LITHIUM, MANGANESE]
description: "Description for Material Composition"
hazardousSubstances: [
{
category: "Acute Toxicity"
class: ACUTE_TOXICITY
classification: "Acute Tox. 4Rep. 1BS-TOT RE 1"
concentration: 0.2599
identifier: "Pb, EC: 170-17-6"
impact: ["Specific Organ Toxicity"]
location: { componentId: "Cell", componentName: "C18098" }
name: "Lead"
relatedIdentifiers: "CAS: 3727-5-10"
}
{
category: "Skin Corrosion or Irritation"
class: SKIN_CORROSION_OR_IRRITATION
classification: "Acute Tox. 4Rep. 2Skin Sens. 1"
concentration: 0.9518
identifier: "Ag, EC: 119-78-5"
impact: ["Skin sensitivity"]
location: { componentId: "Cell", componentName: "C27837" }
name: "Silver"
relatedIdentifiers: "CAS: 3662-81-4"
}
{
category: "Eye Damage or Irritation"
class: EYE_DAMAGE_OR_IRRITATION
classification: "Eye Dmg. 4Rep. Irr. 1"
concentration: 2.8382
identifier: "Li, EC: 53-91-10"
impact: ["Water reaction"]
location: { componentId: "Cell", componentName: "C26998" }
name: "Lithium"
relatedIdentifiers: "CAS: 4926-34-8"
}
]
lastUpdated: "2024-04-08T03:10:33"
lastUpdatedBy: "V-Guard Auditor"
materials: [
{
materialIdentifier: "LiCoO2"
materialLocation: {
componentId: "Cell Cathode"
componentName: "Cell-LiCoO2"
}
materialName: "Lithium Cobalt Oxide"
weight: 10
}
]
title: "Material Composition"
}
performance: {
blockchainVerification: UNVERIFIED
description: "Description for Performance"
internalResistance: {
current: [{ dateTime: "2023-09-10T00:50:36", value: 0.0801 }]
initial: 0.4172
}
lastUpdated: "2024-05-01T15:17:09"
lastUpdatedBy: "V-Guard Auditor"
lifetime: {
capacityThresholdExhaustion: 66
capacityThroughput: 986
cRate: 3.1068
currentDischargeCycles: 25
energyThroughput: 40
expectedChargeCycles: 2503
lifetimeReferenceTest: "IEC 19982-2023"
putIntoService: "28.07.2024"
ratedCapacity: 89
soceThresholdForExhaustion: 72
warrantyPeriod: 67
}
negativeEvents: [
{
description: "Number of structural critical acceleration (accidents): 1"
}
{ description: "Number of deep charge event: 1" }
]
powerCapability: {
fade: 74
maximumPermitted: 85
original: [
{ atSoc: 79.2686, powerCapabilityAt: 172.4556 }
{ atSoc: 51.3321, powerCapabilityAt: 123.0252 }
{ atSoc: 25.3023, powerCapabilityAt: 98.6198 }
{ atSoc: 5.4602, powerCapabilityAt: 60.8151 }
]
ratio: 67
remaining: [
{
atSoc: 77.7177
powerCapabilityAt: 136.513
updatedAt: "2024-06-08T04:03:00"
}
{
atSoc: 45.4688
powerCapabilityAt: 105.599
updatedAt: "2024-07-09T07:21:05"
}
{
atSoc: 37.1014
powerCapabilityAt: 84.2698
updatedAt: "2024-08-01T16:25:51"
}
{
atSoc: 16.9704
powerCapabilityAt: 62.5503
updatedAt: "2024-03-05T07:00:02"
}
]
}
roundtripEfficiency: {
currentSelfDischargingRate: [
{ dateTime: "2024-01-22T14:04:51", value: 0.8195 }
]
initialSelfDischargingRate: 2
}
specification: {
capacityFade: [{ dateTime: "2024-02-10T13:33:41", value: 68.4405 }]
initialSelfDischarge: 284
maximumVoltage: 440
minimumVoltage: 370
nominalVoltage: 400
remainingCapacity: [
{ dateTime: "2023-12-10T20:55:33", value: 58.5355 }
]
stateOfCertifiedEnergy: [
{ dateTime: "2024-07-31T16:40:39", value: 60.1789 }
]
stateOfCharge: [{ dateTime: "2024-03-12T06:52:57", value: 28.8819 }]
ubeCertified: 3490
ubeRemaining: [{ dateTime: "2023-11-29T00:59:36", value: 2780.8494 }]
}
temperatureConditions: {
temperatureRangeIdleState: { high: 24, low: -45 }
timeExtremeHighTemp: 116
timeExtremeLowTemp: 89
}
title: "Performance"
}
revisionPassportId: ""
supplyChain: {
blockchainVerification: UNVERIFIED
description: "Description for Supply Chain"
dueDiligenceReport: "https://vguard.com/sdd-report.pdf"
euTaxonomyDisclosureStatement: "https://vguard.com/eutd-statement.pdf"
lastUpdated: "2024-02-11T19:31:35"
lastUpdatedBy: "V-Guard Auditor"
sustainabilityReport: "https://vguard.com/sustainability-report.pdf"
thirdPartyAudit: "https://vguard.com/audit-certificate.vc"
title: "Supply Chain"
}
}
)
}
Delete passport
How to use
mutation {
deletePassportInstance(
id: "did:web:www.circulor.io:passport-instances:acme-123"
)
}
Updating dynamic properties in an existing battery pass
How to use
There are dynamic properties belonging to our battery passport model. Those properties can be updated over time. We store them as a time-lapsed array within a record, so we will know, over time, the lifetime of a dynamic property's update. We have the following dynamic properties we offer updates to:
- State of Health
- Capacity Fade
- Ube Remaining
- State of Charge
- Remaining Capacity
- State Of Certified Energy (SoCE)
- Internal Resistance
Note that we can update them in batches, by informing a passport ID and its property value.
input DynamicPropertyUpdateRequestInput {
passportId: String!
propertyValue: Float!
}
type MutationType {
updateCapacityFade(items: [DynamicPropertyUpdateRequestInput]): Boolean!
updateUbeRemaining(items: [DynamicPropertyUpdateRequestInput]): Boolean!
updateStateOfCharge(items: [DynamicPropertyUpdateRequestInput]): Boolean!
updateRemainingCapacity(items: [DynamicPropertyUpdateRequestInput]): Boolean!
updateStateOfCertifiedEnergy(
items: [DynamicPropertyUpdateRequestInput]
): Boolean!
updateCurrentInternalResistance(
items: [DynamicPropertyUpdateRequestInput]
): Boolean!
}
How it works
The implementation in each provider is essentially just a dataset update. As only a few values are being hashed, changing dynamic properties will not be reported as a change.
IPK Data Source
This is currently not accessible in the UI, only through the API.
There is a data source which is using a server from IPK to serve some data for a battery passport, showcasing the possibility to use NGSI-LD to collect data for a battery passport.
How to use
Go to a provider API, e.g. https://provider-bmw.dev.thebatterypass.io/graphql/, call getIpkData and select the data you're interested in, e.g.
{
getIpkData {
id
performance {
lifetime {
ratedCapacity {
value
}
}
}
}
}
How it works
With this data source, we take some data from IPK's context broker, and generate the rest to create a complete passport. See the source code and this visualisation of the deployment for more context.