{"_id":"@cardog/ocm-client","_rev":"2-fd25e1a65bf391e49a348d45f36cce99","name":"@cardog/ocm-client","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.0":{"name":"@cardog/ocm-client","version":"0.1.0","keywords":["openchargemap","ocm","ev","electric-vehicle","charging-stations","chargers","api-client","typescript","evse","charging-infrastructure","poi","geolocation"],"author":{"name":"Cardog","email":"hello@cardog.io"},"license":"MIT","_id":"@cardog/ocm-client@0.1.0","maintainers":[{"name":"cardog","email":"sam@cardog.io"}],"homepage":"https://github.com/cardog-ai/ocm-client#readme","bugs":{"url":"https://github.com/cardog-ai/ocm-client/issues"},"dist":{"shasum":"8c653275c567acc5cfc3eb33e76ed6e01feba582","tarball":"https://registry.npmjs.org/@cardog/ocm-client/-/ocm-client-0.1.0.tgz","fileCount":10,"integrity":"sha512-z0PlLqnTef87Wa1g7rWKFoGJpVEnZmkltdTGfCFmSGTRoYUIJo+yjDrs1cz96vqQ2xAaGJjoM08xkWD+CW+uRw==","signatures":[{"sig":"MEUCIB4oGufCYsTY9uD6IV2xivXrVZEGYQIJdjEivlLFVZ1TAiEAhpwOywrjqoNG+SVV/P0sgWJgja42V9v6uNgl8NOR6pE=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":122647},"main":"./dist/index.cjs","type":"module","_from":"file:cardog-ocm-client-0.1.0.tgz","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=18.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"scripts":{"dev":"tsup --watch","lint":"eslint src --ext .ts","test":"vitest run","build":"tsup","clean":"rm -rf dist","format":"prettier --write \"src/**/*.ts\"","lint:fix":"eslint src --ext .ts --fix","typecheck":"tsc --noEmit","test:watch":"vitest","format:check":"prettier --check \"src/**/*.ts\""},"_npmUser":{"name":"cardog","email":"sam@cardog.io"},"_resolved":"/private/var/folders/tq/9s6q39jd7m58p06gpnh9136r0000gn/T/bab74b17670db39475d59f1f9556065e/cardog-ocm-client-0.1.0.tgz","_integrity":"sha512-z0PlLqnTef87Wa1g7rWKFoGJpVEnZmkltdTGfCFmSGTRoYUIJo+yjDrs1cz96vqQ2xAaGJjoM08xkWD+CW+uRw==","repository":{"url":"git+https://github.com/cardog-ai/ocm-client.git","type":"git"},"_npmVersion":"11.0.0","description":"TypeScript client for the Open Charge Map API - access the world's largest open database of EV charging stations","directories":{},"sideEffects":false,"_nodeVersion":"22.13.1","_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.0","eslint":"^8.57.0","vitest":"^2.0.0","prettier":"^3.2.0","typescript":"^5.3.0","@types/node":"^20.10.0","eslint-config-prettier":"^9.1.0","@typescript-eslint/parser":"^7.0.0","@typescript-eslint/eslint-plugin":"^7.0.0"},"_npmOperationalInternal":{"tmp":"tmp/ocm-client_0.1.0_1767137602389_0.9724516225654205","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@cardog/ocm-client","version":"0.1.1","description":"TypeScript client for the Open Charge Map API - access the world's largest open database of EV charging stations","author":{"name":"Cardog","email":"hello@cardog.io"},"license":"MIT","type":"module","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"main":"./dist/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","sideEffects":false,"scripts":{"build":"tsup","dev":"tsup --watch","typecheck":"tsc --noEmit","lint":"eslint src --ext .ts","lint:fix":"eslint src --ext .ts --fix","format":"prettier --write \"src/**/*.ts\"","format:check":"prettier --check \"src/**/*.ts\"","clean":"rm -rf dist","prepublishOnly":"pnpm run clean && pnpm run build","test":"vitest run","test:watch":"vitest"},"keywords":["openchargemap","ocm","ev","electric-vehicle","charging-stations","chargers","api-client","typescript","evse","charging-infrastructure","poi","geolocation"],"repository":{"type":"git","url":"git+https://github.com/cardog-ai/ocm-client.git"},"bugs":{"url":"https://github.com/cardog-ai/ocm-client/issues"},"homepage":"https://github.com/cardog-ai/ocm-client#readme","engines":{"node":">=18.0.0"},"devDependencies":{"@types/node":"^20.10.0","@typescript-eslint/eslint-plugin":"^7.0.0","@typescript-eslint/parser":"^7.0.0","eslint":"^8.57.0","eslint-config-prettier":"^9.1.0","prettier":"^3.2.0","tsup":"^8.0.0","typescript":"^5.3.0","vitest":"^2.0.0"},"_id":"@cardog/ocm-client@0.1.1","_nodeVersion":"22.13.1","_npmVersion":"11.0.0","dist":{"integrity":"sha512-VLwV1FsxTGk08lBYXtCbAWSuXAuF097DtOJY+MWqghGz8vEe6hVepnG6a/bmU8tLZsVpq+xYSscIT7akpLKloQ==","shasum":"9eb808b5a998061296ad3ef5c1b5b6342e129f86","tarball":"https://registry.npmjs.org/@cardog/ocm-client/-/ocm-client-0.1.1.tgz","fileCount":10,"unpackedSize":122750,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIBvETqtMtlfSGGbcOv3T2aEu4C737u4no6UOcE6mm7lPAiAHKHBplK6pa78B8mcd5oxyGL7crzuqfc4NzXyzmh3tmA=="}]},"_npmUser":{"name":"cardog","email":"sam@cardog.io"},"directories":{},"maintainers":[{"name":"cardog","email":"sam@cardog.io"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/ocm-client_0.1.1_1767800698351_0.10826897550898562"},"_hasShrinkwrap":false}},"time":{"created":"2025-12-30T23:33:22.324Z","modified":"2026-01-07T15:44:58.673Z","0.1.0":"2025-12-30T23:33:22.540Z","0.1.1":"2026-01-07T15:44:58.488Z"},"bugs":{"url":"https://github.com/cardog-ai/ocm-client/issues"},"author":{"name":"Cardog","email":"hello@cardog.io"},"license":"MIT","homepage":"https://github.com/cardog-ai/ocm-client#readme","keywords":["openchargemap","ocm","ev","electric-vehicle","charging-stations","chargers","api-client","typescript","evse","charging-infrastructure","poi","geolocation"],"repository":{"type":"git","url":"git+https://github.com/cardog-ai/ocm-client.git"},"description":"TypeScript client for the Open Charge Map API - access the world's largest open database of EV charging stations","maintainers":[{"name":"cardog","email":"sam@cardog.io"}],"readme":"# @cardog/ocm-client\n\n[![npm version](https://img.shields.io/npm/v/@cardog/ocm-client.svg)](https://www.npmjs.com/package/@cardog/ocm-client)\n[![npm downloads](https://img.shields.io/npm/dm/@cardog/ocm-client.svg)](https://www.npmjs.com/package/@cardog/ocm-client)\n[![CI](https://github.com/cardog-ai/ocm-client/actions/workflows/ci.yml/badge.svg)](https://github.com/cardog-ai/ocm-client/actions/workflows/ci.yml)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.3+-blue.svg)](https://www.typescriptlang.org/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nA TypeScript client for the [Open Charge Map](https://openchargemap.org) API — the world's largest open database of EV charging stations.\n\n## About Open Charge Map\n\n[Open Charge Map (OCM)](https://openchargemap.org) 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.\n\n**This is an unofficial client library.** Please consider [supporting OCM](https://opencollective.com/openchargemap) if you find it useful.\n\n## Installation\n\n```bash\n# npm\nnpm install @cardog/ocm-client\n\n# pnpm\npnpm add @cardog/ocm-client\n\n# yarn\nyarn add @cardog/ocm-client\n```\n\n## Quick Start\n\n```typescript\nimport { createOCMClient } from \"@cardog/ocm-client\";\n\n// Get your API key at https://openchargemap.org/site/profile\nconst client = createOCMClient({\n  apiKey: \"your-api-key\",\n});\n\n// Search for nearby charging stations\nconst stations = await client.searchPOI({\n  latitude: 37.7749,\n  longitude: -122.4194,\n  distance: 10,\n  distanceunit: \"km\",\n});\n\nconsole.log(`Found ${stations.length} charging stations`);\n```\n\n## Features\n\n- Full TypeScript support with comprehensive type definitions\n- ESM and CommonJS builds\n- All OCM API v4 endpoints covered\n- Standard enums for connection types, status types, etc.\n- Structured error handling\n- Zero dependencies (uses native `fetch`)\n\n## API Reference\n\n### Creating a Client\n\n```typescript\nimport { createOCMClient, OCMClient } from \"@cardog/ocm-client\";\n\nconst client = createOCMClient({\n  apiKey: \"your-api-key\",      // Required - get one at openchargemap.org\n  baseUrl: \"https://api.openchargemap.io\", // Optional\n  timeout: 30000,              // Optional, in milliseconds\n});\n```\n\n### Searching Charging Stations\n\n```typescript\n// Basic location search\nconst stations = await client.searchPOI({\n  latitude: 37.7749,\n  longitude: -122.4194,\n  distance: 25,\n  distanceunit: \"miles\",\n  maxresults: 100,\n});\n\n// Filter by connector type\nimport { StandardConnectionTypes } from \"@cardog/ocm-client\";\n\nconst ccsStations = await client.searchPOI({\n  latitude: 37.7749,\n  longitude: -122.4194,\n  distance: 50,\n  connectiontypeid: [\n    StandardConnectionTypes.CCSCombo1,\n    StandardConnectionTypes.CCSCombo2,\n  ],\n  minpowerkw: 50, // DC fast chargers only\n});\n\n// Filter by country\nconst ukStations = await client.searchPOI({\n  countrycode: \"GB\",\n  maxresults: 500,\n});\n\n// Get as GeoJSON (great for mapping)\nconst geojson = await client.searchPOIGeoJSON({\n  latitude: 37.7749,\n  longitude: -122.4194,\n  distance: 10,\n});\n```\n\n### Get a Single Station\n\n```typescript\nconst station = await client.getPOI(123456);\n\nif (station) {\n  console.log(station.AddressInfo.Title);\n  console.log(station.Connections);\n  console.log(station.OperatorInfo?.Title);\n}\n```\n\n### Reference Data\n\nOCM uses lookup tables for connection types, operators, status types, etc. Fetch and cache this data locally:\n\n```typescript\nconst refData = await client.getReferenceData();\n\n// Connection types (J1772, CCS, CHAdeMO, Tesla, etc.)\nconsole.log(refData.ConnectionTypes);\n\n// Status types (Operational, Not Operational, etc.)\nconsole.log(refData.StatusTypes);\n\n// Usage types (Public, Private, Membership Required, etc.)\nconsole.log(refData.UsageTypes);\n\n// Network operators (ChargePoint, Electrify America, etc.)\nconsole.log(refData.Operators);\n\n// Countries\nconsole.log(refData.Countries);\n```\n\n### Syncing Updates\n\nEfficiently sync changes since your last update:\n\n```typescript\nconst lastSync = new Date(\"2024-01-01\");\nconst updates = await client.getPOIUpdates(lastSync, {\n  countrycode: \"US\",\n});\n```\n\n### Authentication & Submissions\n\nFor submitting new stations or comments, you'll need to authenticate:\n\n```typescript\n// Authenticate (stores session token automatically)\nawait client.authenticate({\n  EmailAddress: \"user@example.com\",\n  Password: \"password\",\n});\n\n// Submit a new charging station\nconst result = await client.submitPOI({\n  AddressInfo: {\n    Title: \"New Charging Station\",\n    AddressLine1: \"123 Main St\",\n    Town: \"San Francisco\",\n    StateOrProvince: \"CA\",\n    CountryID: 2, // USA\n    Latitude: 37.7749,\n    Longitude: -122.4194,\n  },\n  Connections: [\n    {\n      ConnectionTypeID: 32, // CCS Combo 1\n      PowerKW: 150,\n      Quantity: 2,\n    },\n  ],\n  UsageTypeID: 1, // Public\n  StatusTypeID: 50, // Operational\n});\n\n// Submit a comment/check-in\nawait client.submitComment({\n  ChargePointID: 123456,\n  Comment: \"All chargers working!\",\n  Rating: 5,\n});\n```\n\n## Types\n\nAll types are exported for your convenience:\n\n```typescript\nimport type {\n  // Core entities\n  ChargePoint,\n  POI,               // Alias for ChargePoint\n  ConnectionInfo,\n  AddressInfo,\n  UserComment,\n\n  // Reference data\n  CoreReferenceData,\n  ConnectionType,\n  StatusType,\n  UsageType,\n  OperatorInfo,\n  Country,\n\n  // Enums\n  StandardConnectionTypes,\n  StandardStatusTypes,\n  StandardUsageTypes,\n  StandardCurrentTypes,\n\n  // Requests\n  POISearchParams,\n  AuthenticateResponse,\n} from \"@cardog/ocm-client\";\n```\n\n## Common Connection Types\n\n| ID  | Type                  | Description          |\n| --- | --------------------- | -------------------- |\n| 1   | J1772                 | Type 1 (North America) |\n| 2   | CHAdeMO               | DC Fast (Japanese)   |\n| 25  | Type 2 (Mennekes)     | AC (Europe)          |\n| 27  | Tesla (Roadster)      | Legacy Tesla         |\n| 30  | Tesla Supercharger    | Tesla DC             |\n| 32  | CCS Combo 1           | DC Fast (N. America) |\n| 33  | CCS Combo 2           | DC Fast (Europe)     |\n| 36  | NACS                  | Tesla connector      |\n\n## Error Handling\n\n```typescript\nimport { OCMAPIError } from \"@cardog/ocm-client\";\n\ntry {\n  const stations = await client.searchPOI({\n    latitude: 0,\n    longitude: 0,\n  });\n} catch (error) {\n  if (error instanceof OCMAPIError) {\n    console.error(`API Error ${error.status}: ${error.message}`);\n\n    switch (error.code) {\n      case \"APIKEY_MISSING\":\n        console.error(\"API key is required\");\n        break;\n      case \"APIKEY_INVALID\":\n        console.error(\"Invalid API key\");\n        break;\n      case \"RATE_LIMITED\":\n        console.error(\"Rate limit exceeded\");\n        break;\n    }\n  }\n}\n```\n\n## Rate Limits\n\nOCM 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.\n\nTips:\n- Cache `getReferenceData()` results (they rarely change)\n- Use `getPOIUpdates()` for incremental syncing\n- Batch requests where possible\n\n## Requirements\n\n- Node.js 18+\n- An OCM API key ([get one here](https://openchargemap.org/site/profile))\n\n## Contributing\n\nContributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n## License\n\nMIT © [Cardog](https://cardog.io)\n\n---\n\n**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)](https://opendatacommons.org/licenses/odbl/).\n","readmeFilename":"README.md"}