# Implement the SharpAPI "Address Detector" endpoint

You are adding an integration with SharpAPI's Address Detector API to this codebase. This brief is an alternative to the official SharpAPI SDKs (PHP/Laravel, JavaScript/Node, Python, Flutter, .NET): it describes everything needed to call the API directly over HTTP. If the project already uses a SharpAPI SDK, use the SDK instead.

## What it does

Detects and parses address information from unstructured text. Extracts components like street, city, postal code, country, and more.

## Authentication and base URL

- Base URL: `https://sharpapi.com/api/v1`
- Send `Authorization: Bearer <API key>`, `Accept: application/json` and a `User-Agent` that names your app on every request.
- Read the API key from configuration or an environment variable (for example `SHARPAPI_API_KEY`). Never hard-code or commit it. The key is in the SharpAPI dashboard: https://sharpapi.com/dashboard

## Endpoints



## Example response

```json
{
    "data": {
        "id": "example-uuid",
        "type": "api_job_result",
        "attributes": {
            "type": "content_detect_address",
            "result": {
                "city": "New York",
                "road": "Main Street",
                "unit": "Suite 456",
                "state": "NY",
                "country": "United States",
                "postal_code": "10001",
                "contact_name": "John Doe",
                "country_code": "US",
                "house_number": "123",
                "organization": "Acme Corp"
            },
            "status": "success"
        }
    }
}
```

## Errors to handle

- `429`: rate limited. Wait the `Retry-After` seconds and retry, at most 3 times.
- `402`: the word quota is used up. Do not retry; tell the user to add credits or upgrade.
- `5xx`: retry later with backoff.

## Implementation rules
- Wrap the calls in one small client or service with a typed method for this endpoint, and map the result to a typed object or DTO.
- Track `X-RateLimit-Limit` and `X-RateLimit-Remaining`. When the remaining count drops to 3 or below, slow down.
- `GET https://sharpapi.com/api/v1/ping` checks connectivity and `GET https://sharpapi.com/api/v1/quota` returns the remaining words: use them for a health check.
- Write tests with the HTTP layer mocked: success, `422` validation error, `429` retry, and a missing API key.
- Full API reference: https://sharpapi.com/documentation