API Integration

API Integration

Setup and usage guide for all external APIs consumed by iTravel.

---

Overview

iTravel integrates three external REST APIs and one SDK. All HTTP APIs are accessed through Retrofit 2 singleton clients managed by RetrofitClient.java.

Service	Base URL	Auth Method	Used For
REST Countries	https://restcountries.com/v3.1/	None (public)	Country metadata and flags
Unsplash	https://api.unsplash.com/	Authorization header	Location photos
OpenWeatherMap	https://api.openweathermap.org/data/2.5/	appid query param	Weather overlays
Google Maps SDK	N/A (native SDK)	API key in manifest	Map display and location

---

REST Countries API

No API key required.

Endpoints

GET /v3.1/all?fields=name,flags,region
GET /v3.1/name/{name}?fields=name,flags,region

Response Model (CountryDto)

{
  "name": { "common": "Germany", "official": "Federal Republic of Germany" },
  "flags": { "png": "https://flagcdn.com/w320/de.png", "alt": "..." },
  "region": "Europe"
}

---

Unsplash API

Setup

1. Register at unsplash.com/developers
2. Create an application to get an Access Key
3. Set in Constants.java:

   public static final String UNSPLASH_ACCESS_KEY = "your-key-here";

Endpoint

GET /photos/random
  Header: Authorization: Client-ID {ACCESS_KEY}
  Params: count, query, orientation

Response Model (UnsplashPhotoDto)

{
  "id": "abc123",
  "urls": { "raw": "...", "regular": "...", "thumb": "..." },
  "location": { "name": "Paris", "latitude": 48.8566, "longitude": 2.3522 }
}

---

OpenWeatherMap API

Setup

1. Register at openweathermap.org/api
2. Generate an API key (free tier supports current weather)
3. Set in Constants.java:

   public static final String WEATHER_API_KEY = "your-key-here";

Endpoint

GET /weather?lat={lat}&lon={lon}&appid={key}&units=metric

Response Model (WeatherDto)

{
  "weather": [{ "icon": "01d", "description": "clear sky" }],
  "main": { "temp": 22.5, "humidity": 45 }
}

Weather Icon URL

https://openweathermap.org/img/wn/{icon}@2x.png

---

Google Maps SDK

Setup

1. Enable Maps SDK for Android in Google Cloud Console
2. Create an API key restricted to your app's package name and SHA-1 fingerprint
3. Add to AndroidManifest.xml:

   <meta-data
       android:name="com.google.android.geo.API_KEY"
       android:value="your-key-here" />

Permissions Required

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.INTERNET" />

Components Used

Component	Usage
SupportMapFragment	Embedded map in DiscoverFragment
FusedLocationProviderClient	Current user location for GPS validation
Location.distanceTo()	Proximity check in GPSValidator

---

Retrofit Client Configuration

RetrofitClient.java provides three lazy-initialized singleton instances:

RetrofitClient.getCountriesClient()   // → CountriesApi
RetrofitClient.getUnsplashClient()    // → UnsplashApi
RetrofitClient.getWeatherClient()     // → WeatherApi

All clients use:

• GsonConverterFactory for JSON serialization
• OkHttp with optional HttpLoggingInterceptor (debug builds)

---

Rate Limits

API	Free Tier Limit	Notes
REST Countries	Unlimited	Public, no key
Unsplash	50 requests/hour	Demo key; apply for production
OpenWeatherMap	60 calls/minute	1,000 calls/day on free plan
Google Maps SDK	28,000 map loads/month	Free within $200/month credit

Warning

Production Deployment: Apply for higher-tier Unsplash access and consider caching strategies to stay within rate limits.