# EVpin API

> Score prospective EV charging sites in the United States and Canada.

Full machine-readable reference (OpenAPI 3.1): https://www.evpin.com/api/v1/openapi.json

The EVpin API gives you programmatic access to EVpin's site scoring: the same data and scores as batch uploads, one location per request.

Some response fields only show their full structure to signed-in EVpin users. [Sign in](https://www.evpin.com/sign-in?redirect=%2Fapi%2Fdocs) to see everything.

## Authentication
Anyone in your organization can create an API key in [Organization Settings → API](https://www.evpin.com/dashboard/organization/api) in the EVpin app. Send the key as a bearer token:

```
Authorization: Bearer evp_live_…
```

Every key spends your organization's shared API balance. Keep keys secret and server-side; anyone holding one can spend that balance. A key stops working when the person who created it leaves the organization.

## Pricing
Each successful site score is billed per site to your organization's API balance, in US dollars. Choose the tier per request with `options.tier`: `standard` (the default) returns the score and every signal; `premium` adds utilization of nearby stations and costs more. Volume discounts apply automatically once your organization scores a certain number of new sites in a billing month.

**Your rates, plan credit and balance are in [Organization Settings → API](https://www.evpin.com/dashboard/organization/api).** `GET /api/v1/usage` returns them too.

You are **not** charged when:
- the request fails, for any reason (invalid input, a location we can't score, an error on our end), or
- your organization already scored the same location (within about 10 m) at the same tier or higher in the last 30 days. Re-scoring a `standard` location at `premium` costs only the difference.

Requests are paid from your plan's monthly API credit first, then from prepaid credit, which organization admins add in [Organization Settings → API](https://www.evpin.com/dashboard/organization/api). Organizations without a plan start with some free credit to try the API. If your balance can't cover a request, it fails with `402 insufficient_balance` and nothing is charged.

Every response says what it cost in `billing.amountCharged` and the `X-Amount-Charged` header.

## Rate limits
Site scoring allows 30 requests per minute per organization by default; read endpoints allow 120. Responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds) headers. Over the limit you get `429` with a `Retry-After` header. Contact operations@evpin.com if you need a higher limit.

## Errors
Errors return a JSON body with a stable `error.code`, a human-readable `error.message` and the `error.requestId` (also in the `X-Request-Id` header). Quote the request ID when contacting support at operations@evpin.com.

## Endpoints

### POST /api/v1/sites/score
Score one location. Priced per site (see Pricing). Body:

- `location` (required): either `{ "latitude": number, "longitude": number }` or `{ "address": string }`.
- `options` (optional):
  - `tier`: "standard" (default) or "premium". Premium adds utilization of nearby stations and costs more.
  - `radiusMiles`: 2, 5, 10 (default) or 50. Radius for existing infrastructure and utilization.
  - `chargerLevels`: "all", "level2" or "dcfast" (default).
  - `includeFreeStations`: boolean, default true.
  - `signals`: subset of "amenities", "evAdoption", "traffic", "populationDensity", "existingInfrastructure", "incentives", "affordability", "crime". Default: all.
  - `includeOwnership`: boolean, default false. Also returns ownership and land details for the location.

Returns `overallScore` (0-5), `rating`, per-signal details in `signals`, `nearbyUtilization` (premium only), `utilityCompanies`, `justice40`, `ownership` and `billing`.

Example:

```
curl -X POST https://www.evpin.com/api/v1/sites/score \
  -H "Authorization: Bearer $EVPIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"location": {"address": "1100 Congress Ave, Austin, TX 78701"}}'
```

Uncached requests usually take 3-10 seconds. Use a client timeout of at least 60 seconds.

### GET /api/v1/usage
Balance, rates and request counts for your organization, in US dollars. Free.

## Error codes
- 400 `invalid_request`: body is not valid JSON or does not match the schema; see `error.issues`.
- 401 `invalid_api_key`: missing, malformed or revoked key.
- 402 `insufficient_balance`: the API balance can't cover the request. An organization admin can add credit in Organization Settings → API.
- 422 `location_not_found` or `unsupported_region`: the location cannot be scored.
- 429 `rate_limited`: wait `Retry-After` seconds.
- 500 `internal_error`: retry later; not charged.
- 503 `service_unavailable`: briefly unavailable; wait `Retry-After` seconds and retry. Not charged.