New API documentation available

Hi,

I’m currently updating the API documentation for the current version of the API, any comments or corrections please let me know:

https://openchargemap.org/site/develop/api

The raw OpenAPI schema can be used in other API tools (client generation, documentation etc): https://github.com/openchargemap/ocm-docs/blob/master/Model/schema/ocm-api-schema.yaml

I noticed I also had an old working document for a proposed revision to the data model here: https://github.com/openchargemap/ocm-docs/blob/master/Model/WIP/site.md If anyone is interested in that topic and has their own ideas. I think I was trying to fill the larger gaps between the Open Charge Map model and OCPI, so we could support our existing data and a more refined model for (EVSE equipment level) data.

Hi,

About the new data model I have some questions :

In one Site we can have SupplyEquipments of more than one Operator ?
Tesla and Ionity stalls can be on the same site ?
What’s the distance between two charge points to define two distinct sites ?

SupplyEquipment supersede EquipmentSummary :thinking:
Where is EquipmentSummary in the current data model ? :flushed:

About SupplyEquipment I think it’s a good idea to group all Connections of a single stall :+1:

Didier

Thanks, yes EquipmentSummary is roughly the same information (some of the POI information, plus ConnectionInfo) we already have and can include aggregated information (i.e. we don’t really know the details per item of equipment). We could derive EquipmentSummary from SupplyEquipment (if populated) and perhaps make EquipmentSummary not editable if SuppyEquipment has been populated.

It’s an awkward situation where we have approximate data about equipment but would like to transition to being able to support a model which can have both a full equipment detail and a summary level.

The reason I’ve tried to group multiple networks at one site rather than have multiple sites is the markers will generally overlap each other and it can be left as an exercise for the app developer to visually split these sites by network if they want to. The new position information in SupplyEquipment is the actual physical position of the item of equipment (which could easily be one unit serving two bays, possibly with various connectors or ‘ports’). In reality the equipment configurations vary wildly even on the same network.

I’ve proposed changes to the model before but it hasn’t really taken off, in general the problem is finding people who know enough about the topic (not necessarily me, I’m just a driver like everyone else) and finding people who actually care about the outcome (again, not necessarily me!):
https://github.com/openchargemap/ocm-system/issues/145 (2019)
https://github.com/openchargemap/ocm-system/issues/39 (2015)

Regarding the criteria for having 2 distinct sites close to each other, that’s indeed difficult to specify a rule for. Open to ideas.

I still not understand what you call EquipmentSummary as I cannot see it in the current data model :grimacing:
I don’t know what level of detail you think is relevant. I think we don’t need informations like the brand of the stall, the voltage or amperage. We only need the power delivered, the connector type and the operator.

Site :
In this situation, it may makes sense to create only one site for these two chargers as they are very close.

In this other example, this is more questionable. This is the same parking lot but there is some distance between the two.

Yes, regarding equipment grouping at sites, it’s a difficult problem. If we provide the information grouped by site it’s easier for consumers to then optionally break the information apart, if we present it as separate data then it would be up to consumers to (optionally) merge site markers.

The EquipmentSummary is not explicitly present in the current data model, it is a new proposal for how to present the existing (legacy) information we currently have without forcing data to be split into per-EVSE level information. If we can alternatively come up with a model that combines both the summary information we do have, with per-EVSE grouping, then we can merge the models into one. The more I think about the more I think we could just have a flag on the SupplyEquipment model to indicate that the data has not yet been split into per-EVSE information, then the editor UI would allow the user to perform that split and migrate it. This would remove the need to have EquipmentSummary.(which is redundant information if you have SupplyEquipment).

The primary objective of the data model change is to be able to accept data from network operators which identifies their equipment at the port level in a well structured way (which the existing model doesn’t really do).

We would intend to import and export OCPI data (and other formats): https://github.com/ocpi/ocpi so we also need to close the gaps between that and the model we have. We could just entirely adopt OCPI but I don’t know how we would migrate our existing data to that model.

Ok, so to ensure I’ve got this right…

  1. OCM talks to the CPO/CSO using OCPI.
  2. Then under the covers, the CPO/CSO retrieves data from the EVSE using OCPP (or possibly it accesses cached data), and
  3. The data is returned (as described above) to OCM (by the aforementioned OCPI protocol)

OCM <==OCPI==> CPO <==OCPP==> EVSE

Yes?

Yes. conceptually, although we do none of that currently. Our current data is static (it does not have live status updates) and the handful of [custom] imports we have built in the past are slowly being phased out.

There is a wobbly line between having crowdsourced data (which you can easily have an open data license on) and having imported data (where each data source has a license, which is hopefully an non-restrictive open data license variant). Typically connector level data (i.e. connector unique network id etc) is only available from the network itself, not via crowdsourcing.

Our current data model lacks the explicit grouping (by EVSE) of individually addressable equipment connectors, but it’s only really a minor model change to add that grouping. The larger problem is maintaining compatibility so that apps/services using our data notice no difference and even if we change our model we can still provide useful data transformed into the old model.

The other problem (for me) is that I don’t have time to work on any of this and I’m definitely not the best person to speak with individual networks [if we even should].

Long term I’d like us to provide a clear, singular method for networks to push data to us (and possibly stream status updates), the act of which licenses the data under a single open data license. No individual network agreements, no special treatment. Some more thought around whether network submitted data should be editable by users is required. This has actually been the idea since the start, it just has never happened mostly because it relies on me to make it happen.

Did you see the part on my profile where I said that I’m unemployed?

1 Like

I very much like this.

Well, if you’ve got time on your hands! OCM has been a hobby of mine for 10 years but if we could find a way to fund it’s development (and promotion) that would be great for progress.

As mentioned on the other map icon thread, OCMs primary objective is to be the open data source for charging locations. In an ideal world, apps like PlugShare (the defacto standard for check-ins etc) etc would use our data instead of maintaining their own, and corrections would be fed directly to our database or funneled back to the networks to update their source data. Apps and services will come and go, I’d rather their data didn’t.

What we currently have is a slightly clumsy mash-up of that idea and the world has moved on in the intervening years, so we have an opportunity to reset, confirm if our project goals are the same (I think they are/should be) and prepare for the next 10 years.

For my own part I simultaneously want to be able to work on it more but regularly can barely face working on it (see also: Retirement of Data Imports etc).

If you’re keen to work on certain areas please do play around with stuff, let me know if you need something (I’ll update the old database clone here ocm-docs/Database/Clone at master · openchargemap/ocm-docs · GitHub) and if you have an idea for stuff to work on please raise it before spending too much time on something so we can be sure it’s the right direction.

I’ve you’re a keen people person/communicator (I’m not) then feel free to reach out to parties that could perhaps be involved. For instance perhaps Tritium in Aus has contacts and could connect us to willing data contributors, or perhaps Chargefox would provide an example feed. Fastned were going to give us an OCPI feed but it fell through when it came to the open data agreement (this also happened with Google and Apple Maps circa 2015!).

In line with the theme of “next 10 years”, I think we need to move to .NET 6 - by that I mean get rid of all the deprecated code. That’s all that needs to be done right now in that space. It means that when we get .NET 6.1 or 7 or whatever, it will simply just continue working (or mean less work to continue working). This of course will also mean that I can get a little more used to your coding style, plus you can see what I do.

Does this mean that they didn’t want the data to be open?

Sure thing, everything should be .net 6 now but it is indeed a legacy code base in some parts (it was built API first, just before REST apis were a thing and before JSON was the most popular default for data feeds).

We currently host everything in Windows in an Azure VM (paradoxically, our SQL Server database is running on Linux) because we have $10k of azure open source credits until June, but before that we had one windows VM on AWS and multiple linux VMS acting as read only API mirrors).

Right - so we need a marketing guy to get onboard between now and June to secure funding going forward?

I’m a member of TOCA and TOCWA, and am regularly participating in EV promotional events. I’ll start asking around.

Fastned wanted a special data agreement signed, I wanted them to just give us the data under an Open Data license, we didn’t agree on us relicensing the data as open data (which is kind of the point), so it stalled.

Google got as far as reviewing with lawyers but they didn’t like our Creative Commons Share-Alike license, which I was prepared to change for just CC with Attribution but then they just got cold feet. Apple maps I think just lost their way in terms of management reshuffles as the initial reception for Apple maps wasn’t great when it launched.

Other organisations which may be using OCM data (they have contact us to say is it ok if we use this data/api) include:

  • Jaguar Landrover
  • Kia (Soul EV)
  • Rimac
  • Mapbox (navigation/routing products)
  • Autotrader

Yeah, I do find that people can’t really get past PlugShare in conversations but see how you go. Most people not being developers can’t really see the point of Open Charge Map.

And Open Street Map. They’re also happily using the data.