Custom Connector
Open Charge Map Connector
Global
The Open Charge Map Connector provides seamless integration with the Open Charge Map API, enabling access to a global database of electric vehicle (EV) charging locations. It supports retrieving charging station data, reference data, user authentication, and user-submitted comments and media, plus the API’s OpenAPI specification — acting as a proxy for navigation, EV management, and user engagement applications.
Overview
Integration Overview
This document provides a detailed guide for each integration point of the Open Charge Map API, including its purpose, configuration, parameters, and workflow support.
- getPOI. Retrieves a list of EV charging locations (Points of Interest) based on geographic or other filters.
- getReferenceData. Retrieves core reference data (charger types, operators, countries) for interpreting POI data.
- authenticateUser. Authenticates a user to obtain a JWT token for submitting comments or media.
- submitComment. Submits a user comment or check-in for a specific charging location.
- submitMediaItem. Submits a photo for a specific charging location.
- getOpenAPI. Retrieves the OpenAPI specification for the API.
Documentation
Detailed Integration Documentation
POI Retrieval
| Action | getPOI |
|---|---|
| Purpose | Retrieves a list of EV charging locations (POIs) filtered by criteria such as location, country, or charger type. The primary entry point for charging station data. |
| Parameters | Required: key – your API key (register at openchargemap.org → My Profile → My Apps). Optional: output (json/xml), countrycode (ISO alpha-2), maxresults, latitude/longitude, distance, distanceunit (miles/km), operatorid, connectiontypeid, levelid, usagetypeid, statustypeid, dataproviderid, boundingbox, compact, verbose, includecomments. |
| Configuration | Configure the base URL via CONNECTOR_ENV_OPENCHARGEMAP_BASE_URL (e.g. https://api.openchargemap.io/v3). |
| Output | Successful: JSON array of POI objects (ID, UUID, AddressInfo, Connections, StatusTypeID, DateLastStatusUpdate). Failure: error details (invalid-api-key). |
| Workflow example | Execute getPOI with key and countrycode=US, maxresults=10, then display charging stations in a navigation app or map. |
Reference Data Retrieval
| Action | getReferenceData |
|---|---|
| Purpose | Retrieves core reference data (charger types, connection types, countries) for interpreting POI data or building selection interfaces. |
| Parameters | Required: key. Optional: countryid – comma-separated country IDs. |
| Configuration | Configure the connector with the correct base URL. |
| Output | Successful: JSON with ChargerTypes, ConnectionTypes, Countries, Operators, StatusTypes arrays. Failure: error details (invalid-api-key). |
| Workflow example | Execute getReferenceData with key, then populate dropdowns for charger types or countries and save IDs for filtering getPOI requests. |
User Authentication
| Action | authenticateUser |
|---|---|
| Purpose | Authenticates a user with an Open Charge Map account to obtain a JWT token for submitting comments or media. |
| Parameters | Required: key, emailaddress, password. Optional: None. |
| Configuration | Requires a valid Open Charge Map account. Configure the connector with the correct base URL. |
| Output | Successful: JSON with UserProfile, access_token (JWT), Metadata. Failure: error details (invalid-credentials). |
| Workflow example | Execute authenticateUser with key, emailaddress, and password, then save the access_token for submitComment or submitMediaItem. |
Comment Submission
| Action | submitComment |
|---|---|
| Purpose | Submits a user comment or check-in for a specific charging location to enhance community-driven data. |
| Parameters | Required: key, chargePointID (POI ID from getPOI). Optional: commentTypeID, userName, comment (max 4000 chars), rating (1–5), relatedURL, checkinStatusTypeID. Headers: Authorization: Bearer JWT token. |
| Configuration | Requires a valid JWT token from authenticateUser. Configure the correct base URL. |
| Output | Successful: JSON with status and description (OK). Failure: error details (invalid-charge-point-id). |
| Workflow example | Authenticate to obtain a JWT, then execute submitComment with key, chargePointID, and optional comment/rating. |
Media Item Submission
| Action | submitMediaItem |
|---|---|
| Purpose | Submits a photo for a specific charging location to enhance visual documentation. |
| Parameters | Required: key, chargePointID, imageDataBase64 (Base64-encoded JPEG/PNG). Optional: comment. Headers: Authorization: Bearer JWT token. |
| Configuration | Requires a valid JWT token from authenticateUser. Configure the correct base URL. |
| Output | Successful: JSON with status and description (OK). Failure: error details (invalid-image-data). |
| Workflow example | Authenticate, convert an image to Base64, then execute submitMediaItem with key, chargePointID, and imageDataBase64. |
OpenAPI Specification Retrieval
| Action | getOpenAPI |
|---|---|
| Purpose | Retrieves the OpenAPI 3.0.3 specification (YAML) for the Open Charge Map API, useful for documentation, testing, or client generation. |
| Parameters | Required: key. Optional: None. |
| Configuration | Configure the connector with the correct base URL. |
| Output | Successful: YAML document with openapi, info, servers, paths. Failure: error details (invalid-api-key). |
| Workflow example | Execute getOpenAPI with key, then validate the spec with swagger-cli or load it into Swagger UI. |
Example Workflow: Charging Station Data Collection and Contribution
| Retrieve reference data | Execute getReferenceData with key and save IDs (ConnectionTypeID, CountryID) for filtering or UI elements. |
|---|---|
| Query charging stations | Execute getPOI with key, countrycode=US, maxresults=10 and display stations on a map or list. |
| Authenticate user | Execute authenticateUser to obtain a JWT token and save the access_token. |
| Submit comment | Execute submitComment with key, chargePointID, comment, and the Authorization header. |
| Submit media | Convert a photo to Base64 and execute submitMediaItem with key, chargePointID, imageDataBase64, and Authorization header. |
| Retrieve API spec | Execute getOpenAPI with key and use the YAML for documentation or client generation. |
Troubleshooting Swagger UI Issues
| CORS restrictions | Check Developer Tools (Network tab) for CORS errors. Use a CORS proxy or host Swagger UI locally (http-server --cors); contact Open Charge Map support to confirm CORS support. |
|---|---|
| OpenAPI spec errors | Validate the spec from getOpenAPI using swagger-cli validate openapi.yaml and fix errors like missing items for array parameters (countryid, operatorid). |
| Large responses | Limit responses with maxresults=10 or compact=true for getPOI; disable syntax highlighting if hosting locally. |
| Authentication issues | Ensure the API key is set in the Authorize dialog; for submitComment and submitMediaItem include the JWT token as Authorization: Bearer YourJWTToken. |
| Hosting issues | Avoid running Swagger UI from a file:// URL; host it on a web server (e.g. http://localhost:8080). |
Support
For technical support, contact custom-connectors-support@isolutions.sa.