@cardog/ocm-client


A TypeScript client for the Open Charge Map API — the world's largest open database of EV charging stations.

About Open Charge Map

Open Charge Map (OCM) is a non-commercial, community-driven project that provides free access to EV charging location data worldwide. Since 2011, OCM has been the go-to open data source for EV charging infrastructure.

This is an unofficial client library. Please consider supporting OCM if you find it useful.

Installation

``bash


npm

npm install @cardog/ocm-client

pnpm

pnpm add @cardog/ocm-client

yarn

yarn add @cardog/ocm-client
`

Quick Start

`typescript
import { createOCMClient } from "@cardog/ocm-client";

// Get your API key at https://openchargemap.org/site/profile
const client = createOCMClient({
apiKey: "your-api-key",
});

// Search for nearby charging stations
const stations = await client.searchPOI({
latitude: 37.7749,
longitude: -122.4194,
distance: 10,
distanceunit: "km",
});

console.log(Found ${stations.length} charging stations);
`

Features

- Full TypeScript support with comprehensive type definitions
- ESM and CommonJS builds
- All OCM API v4 endpoints covered
- Standard enums for connection types, status types, etc.
- Structured error handling
- Zero dependencies (uses native fetch)

API Reference

$3

`typescript
import { createOCMClient, OCMClient } from "@cardog/ocm-client";

const client = createOCMClient({
apiKey: "your-api-key", // Required - get one at openchargemap.org
baseUrl: "https://api.openchargemap.io", // Optional
timeout: 30000, // Optional, in milliseconds
});
`

$3

`typescript
// Basic location search
const stations = await client.searchPOI({
latitude: 37.7749,
longitude: -122.4194,
distance: 25,
distanceunit: "miles",
maxresults: 100,
});

// Filter by connector type
import { StandardConnectionTypes } from "@cardog/ocm-client";

const ccsStations = await client.searchPOI({
latitude: 37.7749,
longitude: -122.4194,
distance: 50,
connectiontypeid: [
StandardConnectionTypes.CCSCombo1,
StandardConnectionTypes.CCSCombo2,
],
minpowerkw: 50, // DC fast chargers only
});

// Filter by country
const ukStations = await client.searchPOI({
countrycode: "GB",
maxresults: 500,
});

// Get as GeoJSON (great for mapping)
const geojson = await client.searchPOIGeoJSON({
latitude: 37.7749,
longitude: -122.4194,
distance: 10,
});
`

$3

`typescript
const station = await client.getPOI(123456);

if (station) {
console.log(station.AddressInfo.Title);
console.log(station.Connections);
console.log(station.OperatorInfo?.Title);
}
`

$3

OCM uses lookup tables for connection types, operators, status types, etc. Fetch and cache this data locally:

`typescript
const refData = await client.getReferenceData();

// Connection types (J1772, CCS, CHAdeMO, Tesla, etc.)
console.log(refData.ConnectionTypes);

// Status types (Operational, Not Operational, etc.)
console.log(refData.StatusTypes);

// Usage types (Public, Private, Membership Required, etc.)
console.log(refData.UsageTypes);

// Network operators (ChargePoint, Electrify America, etc.)
console.log(refData.Operators);

// Countries
console.log(refData.Countries);
`

$3

Efficiently sync changes since your last update:

`typescript
const lastSync = new Date("2024-01-01");
const updates = await client.getPOIUpdates(lastSync, {
countrycode: "US",
});
`

$3

For submitting new stations or comments, you'll need to authenticate:

`typescript
// Authenticate (stores session token automatically)
await client.authenticate({
EmailAddress: "user@example.com",
Password: "password",
});

// Submit a new charging station
const result = await client.submitPOI({
AddressInfo: {
Title: "New Charging Station",
AddressLine1: "123 Main St",
Town: "San Francisco",
StateOrProvince: "CA",
CountryID: 2, // USA
Latitude: 37.7749,
Longitude: -122.4194,
},
Connections: [
{
ConnectionTypeID: 32, // CCS Combo 1
PowerKW: 150,
Quantity: 2,
},
],
UsageTypeID: 1, // Public
StatusTypeID: 50, // Operational
});

// Submit a comment/check-in
await client.submitComment({
ChargePointID: 123456,
Comment: "All chargers working!",
Rating: 5,
});
`

Types

All types are exported for your convenience:

`typescript
import type {
// Core entities
ChargePoint,
POI, // Alias for ChargePoint
ConnectionInfo,
AddressInfo,
UserComment,

// Reference data
CoreReferenceData,
ConnectionType,
StatusType,
UsageType,
OperatorInfo,
Country,

// Enums
StandardConnectionTypes,
StandardStatusTypes,
StandardUsageTypes,
StandardCurrentTypes,

// Requests
POISearchParams,
AuthenticateResponse,
} from "@cardog/ocm-client";
`

Common Connection Types

| ID | Type | Description |
| --- | --------------------- | -------------------- |
| 1 | J1772 | Type 1 (North America) |
| 2 | CHAdeMO | DC Fast (Japanese) |
| 25 | Type 2 (Mennekes) | AC (Europe) |
| 27 | Tesla (Roadster) | Legacy Tesla |
| 30 | Tesla Supercharger | Tesla DC |
| 32 | CCS Combo 1 | DC Fast (N. America) |
| 33 | CCS Combo 2 | DC Fast (Europe) |
| 36 | NACS | Tesla connector |

Error Handling

`typescript
import { OCMAPIError } from "@cardog/ocm-client";

try {
const stations = await client.searchPOI({
latitude: 0,
longitude: 0,
});
} catch (error) {
if (error instanceof OCMAPIError) {
console.error(API Error ${error.status}: ${error.message});

switch (error.code) {
case "APIKEY_MISSING":
console.error("API key is required");
break;
case "APIKEY_INVALID":
console.error("Invalid API key");
break;
case "RATE_LIMITED":
console.error("Rate limit exceeded");
break;
}
}
}
`

Rate Limits

OCM has soft rate limits (~10,000 requests/day for registered users). The API tracks usage per key per month. Be respectful of the service — it's run by volunteers.

Tips:
- Cache getReferenceData() results (they rarely change)
- Use getPOIUpdates()` for incremental syncing
- Batch requests where possible

Requirements

- Node.js 18+
- An OCM API key (get one here)

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

License

MIT © Cardog

---

Disclaimer: This is an unofficial client library and is not affiliated with or endorsed by Open Charge Map. OCM data is provided under the Open Database License (ODbL).