SDKs overview
Open Charge Map provides developers with access to its global EV charging station database through a RESTful API. To facilitate integration, the project offers official SDKs and supports community-developed libraries across various programming languages. These SDKs abstract the underlying HTTP requests and JSON parsing, allowing developers to focus on application logic rather than API communication specifics. The primary goal of these SDKs is to simplify fetching, filtering, and displaying charging station information, including location, connector types, and availability status.
The API itself is documented with OpenAPI (formerly Swagger) specifications, which enables automatic generation of client libraries in many languages. This approach helps maintain consistency between the API documentation and the generated code, reducing the effort required for developers to get started. Developers can find detailed API specifications for the Open Charge Map data model and available endpoints on the Open Charge Map API v3 documentation. The API supports standard HTTP methods (GET, POST, PUT, DELETE) and uses JSON for request and response bodies, aligning with common web service development practices.
Official SDKs by language
Open Charge Map maintains a set of official client libraries that provide a structured way to interact with its API. These libraries are designed to offer a consistent interface for common operations such as searching for stations, retrieving details, and managing user contributions (where applicable). The following table summarizes key official SDKs:
| Language | Package Name / Repository | Install Command Example | Maturity |
|---|---|---|---|
| C# | OpenChargeMap.NET (via NuGet) | Install-Package OpenChargeMap.NET |
Stable |
| Java | openchargemap-java (via Maven/Gradle) | implementation 'org.openchargemap:openchargemap-java:x.y.z' |
Stable |
| JavaScript | openchargemap-api-client (via npm) | npm install openchargemap-api-client |
Stable |
| PHP | openchargemap/php-api-client (via Composer) | composer require openchargemap/php-api-client |
Stable |
| Python | openchargemap-py (via pip) | pip install openchargemap-py |
Stable |
| Ruby | openchargemap-ruby (via RubyGems) | gem install openchargemap-ruby |
Under Development |
| Go | go-openchargemap (via go get) | go get github.com/openchargemap/go-openchargemap |
Under Development |
Each SDK is typically hosted on its respective language's package manager and includes documentation on class structures, method calls, and error handling. Developers are encouraged to refer to the specific Open Charge Map developer documentation for the most up-to-date versions and detailed API usage examples for each language.
Installation
Installation of Open Charge Map SDKs follows standard practices for each programming ecosystem. Below are general steps for common languages:
JavaScript (Node.js/Browser)
For Node.js projects, use npm or Yarn. In a browser environment, you might include the client library via a CDN or bundle it with a tool like Webpack.
npm install openchargemap-api-client
# Or using Yarn
yarn add openchargemap-api-client
Python
The Python SDK is available through pip, the Python package installer.
pip install openchargemap-py
C# (.NET)
For .NET projects, the NuGet package manager is used to install the C# SDK.
# Via .NET CLI
dotnet add package OpenChargeMap.NET
# Via NuGet Package Manager Console in Visual Studio
Install-Package OpenChargeMap.NET
Java (Maven/Gradle)
For Java applications, dependencies are typically managed with Maven or Gradle. Add the following to your pom.xml (Maven) or build.gradle (Gradle):
<!-- Maven -->
<dependency>
<groupId>org.openchargemap</groupId>
<artifactId>openchargemap-java</artifactId>
<version>x.y.z</version>
</dependency>
// Gradle
implementation 'org.openchargemap:openchargemap-java:x.y.z'
Replace x.y.z with the latest version number, which can be found on the Open Charge Map developer resources page.
Quickstart example
This quickstart example demonstrates how to use the Python SDK to retrieve a list of EV charging stations near a specified location. You will need an API key for most production uses, which can be obtained by registering on the Open Charge Map website.
Python Quickstart: Find Charging Stations
import openchargemap as ocm
# Replace with your actual API key
API_KEY = "YOUR_API_KEY"
# Initialize the client with your API key
client = ocm.Client(api_key=API_KEY)
# Define search parameters
latitude = 51.5074 # Example: London
longitude = -0.1278 # Example: London
max_results = 5
distance = 5 # km
try:
# Search for charging stations
stations = client.search_stations(
latitude=latitude,
longitude=longitude,
max_results=max_results,
distance=distance
)
print(f"Found {len(stations)} charging stations near {latitude}, {longitude}:")
for station in stations:
print(f" - {station.AddressInfo.Title} ({station.AddressInfo.AddressLine1}, {station.AddressInfo.Town})")
print(f" Connections: {', '.join([conn.ConnectionType.Title for conn in station.Connections if conn.ConnectionType])}")
if station.UsageCost:
print(f" Cost: {station.UsageCost}")
else:
print(" Cost: N/A")
except ocm.exceptions.OpenChargeMapException as e:
print(f"An error occurred: {e}")
except Exception as e:
print(f"An unexpected error occurred: {e}")
This script first initializes the Open Charge Map client with an API key. It then calls the search_stations method, passing in geographical coordinates, a maximum number of results, and a search radius in kilometers. The results are iterated, and key information about each charging station, such as its title, address, and available connection types, is printed to the console. Error handling is included to catch API-specific exceptions and general programming errors.
For detailed information on available search parameters and response structures, consult the Open Charge Map API documentation.
Community libraries
Beyond the officially supported SDKs, the Open Charge Map community contributes various libraries and tools that extend functionality or provide integrations in other languages and frameworks. These community efforts often address specific use cases, such as mapping integrations, data visualization, or mobile application development.
Examples of community contributions may include:
- Client wrappers in less common languages: Developers might create clients for languages like Rust, Swift, or Kotlin that are not officially supported by the core team.
- Framework-specific integrations: Libraries tailored for web frameworks like Django, Flask, Ruby on Rails, or front-end frameworks like React or Vue.js, simplifying data display and interaction.
- Mapping library integrations: Tools that directly integrate Open Charge Map data with popular mapping libraries such as Leaflet, Mapbox, or Google Maps, providing pre-built components for displaying charging stations on a map. For example, a library might offer custom markers for different connector types or real-time availability overlays. Google's documentation on Places API for location-based services often includes examples relevant to integrating POI data, which could inspire similar community efforts for Open Charge Map data.
- Data processing scripts: Utilities for parsing, filtering, or augmenting Open Charge Map data for specific analytical purposes or custom database ingestion.
While community libraries can offer flexibility and address niche requirements, their maintenance and support levels can vary. Developers are advised to check the project's activity, documentation, and community engagement before adopting them for production systems. The primary source for discovering these community efforts is typically the Open Charge Map developer hub or community forums.