TucanAPI Documentation

Latest Exchange Rates

Get the latest exchange rates for a base currency against multiple currencies.

Endpoint: GET /rates/latest

Parameters:

• base (optional): Base currency (default: EUR)
• currencies (optional): Comma-separated list of currencies

GET /rates/latest?base=USD¤cies=EUR,GBP&api_key=YOUR_API_KEY

Errors: 400 (Invalid parameters), 401 (Invalid API key)

Example Response

A successful response returns the latest exchange rates for the requested currencies.

{
  "base": "USD",
  "date": "2025-04-30",
  "rates": {
    "EUR": 0.92,
    "GBP": 0.81
  }
}

The response includes the base currency, date of the rates, and the exchange rates for each requested currency.

Historical Exchange Rates

Get historical exchange rates for a specific date.

Endpoint: GET /rates/historical/<date>

Path Parameter:

• date: Date in YYYY-MM-DD format

Query Parameters:

• base (optional): Base currency (default: EUR)
• currencies (optional): Comma-separated list

GET /rates/historical/2025-03-15?base=EUR¤cies=USD,GBP&api_key=YOUR_API_KEY

Errors: 400 (Invalid date or parameters), 401 (Invalid API key)

Example Response

A successful response returns the exchange rates for the specified date.

{
  "base": "EUR",
  "date": "2025-03-15",
  "rates": {
    "USD": 1.08,
    "GBP": 0.84
  }
}

The response includes the base currency, the requested date, and the historical exchange rates for each requested currency.

Currency Conversion

Convert an amount from one currency to another using the latest exchange rates.

Endpoint: GET /rates/convert

Parameters:

• from: Source currency code (required)
• to: Target currency code (required)
• amount: Amount to convert (required)
• date: Historical date (optional)

GET /rates/convert?from=EUR&to=USD&amount=100&api_key=YOUR_API_KEY

Errors: 400 (Missing or invalid parameters), 401 (Invalid API key)

Example Response

A successful response returns the converted amount and the exchange rate used.

{
  "from": "EUR",
  "to": "USD",
  "amount": 100,
  "result": 113.73,
  "rate": 1.1373,
  "date": "2025-04-30"
}

The response includes the source and target currencies, the original amount, the converted result, the exchange rate used, and the date of the rate.

Available Currencies

Get a list of all available currencies supported by the API.

Endpoint: GET /currencies

GET /currencies?api_key=YOUR_API_KEY

Errors: 401 (Invalid API key)

Example Response

A successful response returns a list of all supported currencies with their codes and names.

{
  "currencies": [
    {"code": "USD", "name": "US Dollar"},
    {"code": "EUR", "name": "Euro"}
  ]
}

The response includes an array of currency objects, each with a code and name. The actual response will contain all supported currencies (over 150).

IP Geolocation Lookup

Get geographic and network information for a given IP address.

Endpoint: GET /ip-geolocation

Parameters:

• ip: IP address to look up (required)

GET /ip-geolocation?ip=8.8.8.8&api_key=YOUR_API_KEY

Errors: 400 (Missing or invalid IP), 401 (Invalid API key)

Example Response

A successful response returns detailed location information for the IP address.

{
  "ip": "8.8.8.8",
  "country": "United States",
  "country_code": "US",
  "city": "Mountain View",
  "latitude": 37.4056,
  "longitude": -122.0775,
  "timezone": "America/Los_Angeles"
}

The response includes the IP address, country, city, geographic coordinates, and timezone information.

User-Agent Parser

Parse a user-agent string to extract device, browser, and OS information.

Endpoint: GET /user-agent-lookup

Headers:

• User-Agent: The User-Agent string to parse (required)

GET /user-agent-lookup?api_key=YOUR_API_KEY
User-Agent: Mozilla/5.0 ...

Errors: 400 (Missing User-Agent header), 401 (Invalid API key)

Example Response

A successful response returns detailed information about the browser, operating system, and device.

{
  "user_agent": "Mozilla/5.0 ...",
  "browser": {
    "name": "Chrome",
    "version": "90.0.4430.212"
  },
  "os": {
    "name": "Windows",
    "version": "10"
  },
  "device": {
    "type": "Desktop",
    "brand": null,
    "model": null
  }
}

The response includes the original user-agent string and parsed information about the browser, operating system, and device.

Email Validation

Validate the syntax and deliverability of an email address, and detect common typos.

Endpoint: GET /email-validation

Parameters:

• email: Email address to validate (required)

GET /[email protected]&api_key=YOUR_API_KEY

Errors: 400 (Missing email parameter), 401 (Invalid API key)

Example Response

A successful response returns validation results and suggestions for common typos.

{
  "email": "[email protected]",
  "is_valid": false,
  "is_disposable": false,
  "is_role_account": false,
  "domain": "gnail.com",
  "domain_suggestion": "gmail.com"
}

The response includes validation results and a suggested correction for common typos in the domain name.

Country Information

Get detailed information about a country by its ISO code.

Endpoint: GET /country-data

Parameters:

• code: ISO country code (required)

GET /country-data?code=US&api_key=YOUR_API_KEY

Errors: 400 (Missing or invalid country code), 401 (Invalid API key)

Example Response

A successful response returns comprehensive information about the requested country.

{
  "name": "United States",
  "code": "US",
  "capital": "Washington D.C.",
  "region": "Americas",
  "subregion": "Northern America",
  "population": 331002651,
  "currencies": [
    {
      "code": "USD",
      "name": "United States dollar",
      "symbol": "$"
    }
  ],
  "languages": [
    {
      "code": "en",
      "name": "English"
    }
  ],
  "flag": "🇺🇸"
}

The response includes the country's name, code, capital, region, population, currencies, languages, and flag emoji.

Phone Number Validation

Validate and format international phone numbers, and get carrier information.

Endpoint: GET /phone-validation

Parameters:

• phone: Phone number to validate (required)
• country: ISO country code (optional, default: "US")

GET /phone-validation?phone=+14155552671&country=US&api_key=YOUR_API_KEY

Errors: 400 (Missing phone parameter), 401 (Invalid API key)

Example Response

A successful response returns validation results and formatted phone number.

{
  "phone": "+14155552671",
  "country_code": "US",
  "is_valid": true,
  "type": "mobile",
  "carrier": "Unknown Carrier",
  "formatted": "+1 (415) 555-2671"
}

The response includes validation results, phone type (mobile/landline), carrier information when available, and a properly formatted version of the number.

VAT Number Validation

Validate European VAT numbers and retrieve company information.

Endpoint: GET /vat-validation

Parameters:

• vat: VAT number to validate (required)

GET /vat-validation?vat=DE123456789&api_key=YOUR_API_KEY

Errors: 400 (Missing VAT parameter), 401 (Invalid API key)

Example Response

A successful response returns validation results and company information.

{
  "vat_number": "DE123456789",
  "is_valid": true,
  "country_code": "DE",
  "company_name": "Example Company DE",
  "company_address": "123 Example Street, DE"
}

The response includes validation results and, when available, the registered company name and address associated with the VAT number.