Skip to content

Commit c7b445d

Browse files
cahthuranagclaude
cahthuranag
and
claude
committed
Rewrite README with badges, examples, and API reference
Expand the bare README into a comprehensive guide matching the Python SDK quality: badges, why section, response examples for every method, configuration table, error handling, and links. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent 6328343 commit c7b445d

1 file changed

Lines changed: 201 additions & 27 deletions

File tree

‎README.md‎

Lines changed: 201 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,24 @@
1-
# Exchange Rate API - PHP SDK
1+
# exchangerateapi/sdk
22

3-
Official PHP SDK for the [Exchange Rate API](https://exchange-rateapi.com) exchange rate service.
3+
[![Packagist version](https://img.shields.io/packagist/v/exchangerateapi/sdk.svg)](https://packagist.org/packages/exchangerateapi/sdk)
4+
[![PHP](https://img.shields.io/packagist/php-v/exchangerateapi/sdk.svg)](https://packagist.org/packages/exchangerateapi/sdk)
5+
[![license](https://img.shields.io/packagist/l/exchangerateapi/sdk.svg)](https://github.com/Exchange-RateAPI/exchange-rateapi-php/blob/main/LICENSE)
6+
[![zero dependencies](https://img.shields.io/badge/dependencies-0-brightgreen.svg)](https://packagist.org/packages/exchangerateapi/sdk)
47

5-
Real-time mid-market exchange rates for 160+ currencies, sourced from Reuters (Refinitiv) and interbank market feeds.
8+
**Official PHP SDK for real-time mid-market exchange rates. 160+ currencies, zero external dependencies.**
9+
10+
## Why Choose This SDK?
11+
12+
- **Lightweight** -- Only requires `ext-curl` and `ext-json`, both bundled with PHP by default
13+
- **Real-Time Data** -- Rates updated every 60 seconds from Reuters (Refinitiv) and interbank feeds
14+
- **Mid-Market Rates** -- The true interbank rate -- no hidden spread or markup
15+
- **160+ Currencies** -- Major, minor, and exotic currency pairs
16+
- **PHP 7.4+** -- Works on any modern PHP version, including PHP 8.x
17+
- **Zero Dependencies** -- No Composer packages to audit, no supply chain risk
18+
19+
## Get Your API Key
20+
21+
Ready to start? Get your free API key from [exchange-rateapi.com/register](https://exchange-rateapi.com/register).
622

723
## Installation
824

@@ -12,7 +28,7 @@ composer require exchangerateapi/sdk
1228

1329
## Quick Start
1430

15-
Get your free API key at [exchange-rateapi.com/register](https://exchange-rateapi.com/register).
31+
Get up and running in seconds:
1632

1733
```php
1834
use ExchangeRateAPI\ExchangeRateAPI;
@@ -21,65 +37,223 @@ $client = new ExchangeRateAPI('era_live_your_key_here');
2137

2238
// Get exchange rate
2339
$rate = $client->getRate('USD', 'EUR');
24-
echo "1 USD = {$rate[0]['rate']} EUR\n";
40+
echo "1 USD = {$rate['rate']} EUR\n";
2541

26-
// Convert amount
27-
$result = $client->convert('USD', 'EUR', 100);
28-
echo "\$100 = €{$result['result']}\n";
42+
// Convert an amount
43+
$result = $client->convert('USD', 'EUR', 1000);
44+
echo "\$1,000 = EUR {$result['result']}\n";
2945

30-
// Get historical rates
46+
// Get historical rates for the last 30 days
3147
$history = $client->getHistoricalRates('USD', 'EUR', '30d');
48+
echo "Current rate: {$history['current']['rate']}\n";
3249
foreach ($history['rates'] as $point) {
3350
echo "{$point['time']}: {$point['rate']}\n";
3451
}
3552
```
3653

3754
## API Reference
3855

39-
### `new ExchangeRateAPI($apiKey, $baseUrl, $timeout)`
56+
- [Single Rate](#single-rate) -- Get an exchange rate between two currencies
57+
- [Currency Conversion](#currency-conversion) -- Convert an amount between currencies
58+
- [Rates with Metadata](#rates-with-metadata) -- Get rate data with full metadata
59+
- [Historical Rates by Period](#historical-rates-by-period) -- Preset period lookups (1d/7d/30d/1y)
60+
61+
---
62+
63+
### Single Rate
64+
65+
Get an exchange rate between two currencies with a single call:
66+
67+
```php
68+
// Basic rate lookup
69+
$data = $client->getRate('USD', 'EUR');
70+
echo "1 USD = {$data['rate']} EUR\n";
71+
72+
// With an amount
73+
$data = $client->getRate('USD', 'EUR', 500);
74+
echo "\$500 = EUR {$data['to']['amount']}\n";
75+
```
4076

41-
| Parameter | Type | Default | Description |
42-
|-----------|------|---------|-------------|
43-
| `$apiKey` | `string` | **required** | Your API key ([register free](https://exchange-rateapi.com/register)) |
44-
| `$baseUrl` | `string` | `https://exchange-rateapi.com` | API base URL |
45-
| `$timeout` | `int` | `10` | Request timeout in seconds |
77+
**Response:**
4678

47-
### Methods
79+
```php
80+
[
81+
'from' => ['currency' => 'USD', 'amount' => 1],
82+
'to' => ['currency' => 'EUR', 'amount' => 0.9234],
83+
'rate' => 0.9234,
84+
'source' => 'mid-market',
85+
]
86+
```
4887

49-
| Method | Description |
50-
|--------|-------------|
51-
| `getRate($from, $to, $amount)` | Get exchange rate between two currencies |
52-
| `convert($from, $to, $amount)` | Convert amount between currencies |
53-
| `getRates($source, $target)` | Get rate data with metadata |
54-
| `getHistoricalRates($source, $target, $period)` | Historical rates (1d/7d/30d/1y) |
88+
---
5589

56-
All methods require an API key.
90+
### Currency Conversion
5791

58-
### Error Handling
92+
Convert any amount between currencies -- returns a clean, flat result:
93+
94+
```php
95+
$result = $client->convert('USD', 'EUR', 1000);
96+
echo "\$1,000 = EUR {$result['result']}\n";
97+
echo "Rate used: {$result['rate']}\n";
98+
```
99+
100+
**Response:**
101+
102+
```php
103+
[
104+
'from' => 'USD',
105+
'to' => 'EUR',
106+
'amount' => 1000,
107+
'result' => 923.4,
108+
'rate' => 0.9234,
109+
]
110+
```
111+
112+
---
113+
114+
### Rates with Metadata
115+
116+
Get exchange rates with full metadata for a currency pair:
117+
118+
```php
119+
$data = $client->getRates('USD', 'EUR');
120+
print_r($data);
121+
```
122+
123+
**Response:**
124+
125+
```php
126+
[
127+
[
128+
'source' => 'USD',
129+
'target' => 'EUR',
130+
'rate' => 0.9234,
131+
'time' => '2026-05-25T14:30:00Z',
132+
],
133+
]
134+
```
135+
136+
---
137+
138+
### Historical Rates by Period
139+
140+
Get historical rates using preset periods -- no date math needed:
141+
142+
```php
143+
$history = $client->getHistoricalRates('USD', 'EUR', '30d');
144+
145+
echo "Current rate: {$history['current']['rate']}\n";
146+
echo "Period: {$history['period']}\n";
147+
148+
foreach ($history['rates'] as $point) {
149+
echo "{$point['time']}: {$point['rate']}\n";
150+
}
151+
```
152+
153+
**Available periods:** `1d`, `7d`, `30d`, `1y` (default: `7d`)
154+
155+
**Response:**
156+
157+
```php
158+
[
159+
'source' => 'USD',
160+
'target' => 'EUR',
161+
'period' => '30d',
162+
'current' => ['rate' => 0.9234, 'time' => '2026-05-25T14:30:00Z'],
163+
'rates' => [
164+
['rate' => 0.9187, 'time' => '2026-04-25T14:30:00Z'],
165+
['rate' => 0.9195, 'time' => '2026-04-26T14:30:00Z'],
166+
// ...
167+
],
168+
]
169+
```
170+
171+
---
172+
173+
## Configuration
174+
175+
```php
176+
$client = new ExchangeRateAPI(
177+
apiKey: 'era_live_your_key_here', // Required
178+
baseUrl: 'https://exchange-rateapi.com', // Optional
179+
timeout: 10, // Optional (seconds)
180+
);
181+
```
182+
183+
| Parameter | Type | Default | Description |
184+
| ---------- | -------- | ------------------------------ | -------------------------- |
185+
| `$apiKey` | `string` | -- | Your API key |
186+
| `$baseUrl` | `string` | `https://exchange-rateapi.com` | API base URL |
187+
| `$timeout` | `int` | `10` | Request timeout in seconds |
188+
189+
---
190+
191+
## Error Handling
192+
193+
All errors are thrown as `ExchangeRateAPIException` with an optional HTTP status code:
59194

60195
```php
61196
use ExchangeRateAPI\ExchangeRateAPI;
62197
use ExchangeRateAPI\ExchangeRateAPIException;
63198

199+
$client = new ExchangeRateAPI('era_live_your_key_here');
200+
64201
try {
65202
$rate = $client->getRate('USD', 'INVALID');
66203
} catch (ExchangeRateAPIException $e) {
67-
echo $e->getMessage(); // Error message
68-
echo $e->getStatusCode(); // HTTP status code
204+
echo $e->getMessage(); // "Currency not found"
205+
echo $e->getStatusCode(); // 404
69206
}
70207
```
71208

209+
| Status | Meaning |
210+
| ------ | --------------------------------------- |
211+
| -- | Missing API key (thrown before request) |
212+
| `401` | Invalid API key |
213+
| `404` | Currency code not found |
214+
| `429` | Rate limit exceeded |
215+
| `500` | Server error |
216+
217+
---
218+
219+
## Methods Reference
220+
221+
| Method | Description |
222+
| ----------------------------------------------- | ------------------------------------------- |
223+
| `getRate($from, $to, $amount)` | Get exchange rate between two currencies |
224+
| `convert($from, $to, $amount)` | Convert amount and get a flat result array |
225+
| `getRates($source, $target)` | Get rates with full metadata |
226+
| `getHistoricalRates($source, $target, $period)` | Historical rates by period (1d/7d/30d/1y) |
227+
228+
---
229+
230+
## Zero Dependencies
231+
232+
This SDK uses only PHP extensions that ship with every standard PHP installation:
233+
234+
- **ext-curl** -- HTTP requests
235+
- **ext-json** -- JSON encoding and decoding
236+
237+
No third-party Composer packages. Nothing to audit, nothing to break.
238+
239+
---
240+
72241
## Requirements
73242

74243
- PHP >= 7.4
75244
- ext-curl
76245
- ext-json
77246

247+
---
248+
78249
## Links
79250

80-
- [API Documentation](https://exchange-rateapi.com/docs)
251+
- [API Documentation](https://exchange-rateapi.com/developers)
81252
- [Register (Free)](https://exchange-rateapi.com/register)
82253
- [Dashboard](https://exchange-rateapi.com/profile)
254+
- [Status](https://exchange-rateapi.com/status)
255+
- [GitHub](https://github.com/Exchange-RateAPI/exchange-rateapi-php)
256+
- [Packagist](https://packagist.org/packages/exchangerateapi/sdk)
83257

84258
## License
85259

0 commit comments

Comments
 (0)