UK Market API BETA
Market-namespaced endpoints for UK credit cards. All monetary values are in GBP. The same authentication and response envelope as the core API.
Overview
UK endpoints live under the /api/v1/gb/ namespace. They use the same API key, response envelope, and authentication as the core US API — the only difference is the URL prefix and that all data is scoped to the UK market.
Base URL
https://kokofinance.net/api/v1/gbKey Differences from US API
| Aspect | US API | UK API |
|---|---|---|
| Base path | /api/v1/cards | /api/v1/gb/cards |
| Currency | USD ($) | GBP (£) |
| Card catalog | 150+ US cards | 20 UK cards (growing) |
| Authentication | Same — X-API-Key header | |
| Response format | Same — { success, data, metadata, error } | |
Why a Separate Namespace?
UK developers see only endpoints relevant to the UK market. US-specific endpoints (Schumer Box terms, CFPB data, US changelog) are not exposed under /gb/, keeping the API surface clean and focused.
Endpoints
Four endpoints are currently available in the UK namespace:
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/v1/gb/cards/ |
List all UK credit cards with filtering and pagination |
| GET | /api/v1/gb/cards/{card_id} |
Get full details for a specific UK card |
| POST | /api/v1/gb/cards/search |
Structured search with filters (issuer, fee, type, network) |
| POST | /api/v1/gb/cards/compare |
Compare 2-3 UK cards side-by-side (fast or verbose mode) |
GET /api/v1/gb/cards/
Returns a paginated list of UK credit cards. Supports filtering by issuer, card type, network, max annual fee, and free-text search.
Query Parameters
| Parameter | Type | Description |
|---|---|---|
q | string | Fuzzy search across card name, issuer, and best_for |
issuer | string | Filter by issuer (e.g. HSBC, Barclaycard) |
card_type | string | Filter by card type (e.g. Travel Rewards) |
network | string | Filter by network (Visa, Mastercard, Amex) |
max_annual_fee | integer | Maximum annual fee in GBP |
limit | integer | Results per page (default 20, max 100) |
offset | integer | Pagination offset |
GET /api/v1/gb/cards/{card_id}
Returns the full enriched card object for a UK card, including rewards structure, key benefits, sign-on bonus, and apply URL.
POST /api/v1/gb/cards/search
Structured search that returns matched UK cards ranked by relevance. Accepts the same request body as the US search endpoint.
Request Body
| Field | Type | Description |
|---|---|---|
query | string | Natural-language search query |
issuer | string | Filter by issuer |
card_type | string | Filter by card type |
max_annual_fee | number | Maximum annual fee in GBP |
limit | integer | Max results (default 10) |
POST /api/v1/gb/cards/compare
Compare 2–3 UK credit cards side-by-side. Supports two modes:
- Fast mode (default) — Deterministic calculation using card data. Returns structured comparison with net value, break-even, rewards by category. Typically <100ms.
- Verbose mode (
?mode=verbose) — AI-generated narrative with winner recommendation, fit scores, pros/cons, and use-case recommendations. 2–5 seconds.
Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
mode | string | fast | fast or verbose |
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
card_names | array | Yes | 2–3 card names to compare |
params.spending | object | No | Monthly spending by category (e.g. {"dining": 200, "travel": 300}) |
Examples
List UK Cards
curl https://kokofinance.net/api/v1/gb/cards/ \
-H "X-API-Key: YOUR_API_KEY"Response (truncated)
{
"success": true,
"data": {
"cards": [
{
"card_name": "Gold Card",
"issuer": "American Express",
"annual_fee": 160,
"card_type": "Travel Rewards",
"network": "Amex",
"country_code": "GB",
"currency": "GBP"
},
{
"card_name": "Barclaycard Avios Plus",
"issuer": "Barclaycard",
"annual_fee": 144,
"card_type": "Travel Rewards",
"network": "Visa",
"country_code": "GB",
"currency": "GBP"
}
],
"total": 20,
"limit": 20,
"offset": 0
}
}Search for No-Fee Cards
curl -X POST https://kokofinance.net/api/v1/gb/cards/search \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query": "no annual fee cashback", "max_annual_fee": 0}'Compare Cards (Fast Mode)
curl -X POST https://kokofinance.net/api/v1/gb/cards/compare \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"card_names": ["Gold Card", "Barclaycard Avios Plus"],
"params": {
"spending": {"dining": 200, "travel": 300, "groceries": 400}
}
}'Response (truncated)
{
"success": true,
"data": {
"comparison_table": [
{
"card_name": "Gold Card",
"issuer": "American Express",
"annual_fee": 160.0,
"net_value": -160.0,
"earning_rates": { "base": 1.0 },
"break_even": {
"status": "spending_required",
"monthly_spend_at_base_rate": 2021.0
}
},
{
"card_name": "Barclaycard Avios Plus",
"issuer": "Barclaycard",
"annual_fee": 144.0,
"net_value": -144.0,
"earning_rates": { "base": 1.5 },
"break_even": {
"status": "spending_required",
"monthly_spend_at_base_rate": 1212.0
}
}
],
"currency": "GBP",
"spending_source": "user_provided",
"assumptions": {
"redemption_rate": 0.66,
"benefit_utilization_rate": 0.5,
"point_value": 0.01
}
}
}Compare Cards (Verbose Mode)
curl -X POST "https://kokofinance.net/api/v1/gb/cards/compare?mode=verbose" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"card_names": ["Gold Card", "Barclaycard Avios Plus"]}'Verbose mode returns AI-generated pros/cons, a winner recommendation, fit scores, and use-case recommendations — all with £ currency formatting.
Coming Soon
The following capabilities are planned for the UK namespace:
| Feature | Description | Status |
|---|---|---|
| Portfolio Optimization | Analyze a portfolio of UK cards for spending overlap and gap analysis | Planned |
| Card Recommend | Get card recommendations by spending category | Planned |
| Renewal Analysis | Should you keep or cancel a card at renewal? | Planned |
| Merchant Intelligence | Best card to use at a UK merchant | Planned |
| Expanded Catalog | Additional UK cards from more issuers | Ongoing |
Have a request? Email team@kokofinance.net and let us know what you'd like to see next.