@cardog/ocm-client

@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

# npm
npm install @cardog/ocm-client

# pnpm
pnpm add @cardog/ocm-client

# yarn
yarn add @cardog/ocm-client

Quick Start

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

Creating a Client

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
});

Searching Charging Stations

// 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,
});

Get a Single Station

const station = await client.getPOI(123456);

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

Reference Data

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

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);

Syncing Updates

Efficiently sync changes since your last update:

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

Authentication & Submissions

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

// Authenticate (stores session token automatically)
await client.authenticate({
  EmailAddress: "[e-mail]",
  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:

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

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).