Welcome to the RajaOngkir API V2!

This comprehensive guide will walk you through everything you need to know to get started, including setup, authentication, and choosing the right integration method for your needs. Whether you're building a shipping calculator or any application that requires shipping data, this API has you covered.

Step 1: Register for an API Key

• Go to the RajaOngkir website and sign up for an account.
• After registering, log in to your dashboard.
• Navigate to the API Key section and generate your unique key. This key will be used to authenticate all your API requests.

Step 2: Choose Your Integration Method

RajaOngkir API V2 provides two different approaches for accessing shipping data. Choose the method that best fits your application's user experience:

🔄 Step-by-Step Method (Hierarchical)

Best for: Traditional forms, dropdown menus, structured selections

How it works:

1. Get list of provinces
2. Select province → Get cities in that province
3. Select city → Get districts in that city
4. Select district → Get subdistricts in that district (optional)
5. Use District IDs or Subdistrict IDs for cost calculation

Perfect for: Applications where users prefer guided selection through dropdowns

🔍 Direct Search Method (Instant Search)

Best for: Modern search interfaces, autocomplete, quick lookups

How it works:

1. User types city name directly (e.g., "Jakarta", "Surabaya")
2. Get instant results with complete location details down to Subdistrict level
3. Use Subdistrict IDs for cost calculation

Perfect for: Applications with search boxes or when users know their destination

Step 3: Understand API Endpoints

Based on your chosen method, you'll use different endpoints:

For Step-by-Step Method:

• Search Province Endpoint: Get list of all provinces
• Search City Endpoint: Get cities by province ID
• Search District Endpoint: Get districts by city ID
• Search Subdistrict Endpoint: Get subdistricts by district ID (optional)
• Cost Calculation Endpoint: Calculate shipping costs using District IDs or Subdistrict IDs

For Direct Search Method:

• Search Domestic Destination Endpoint: Direct search by city name (returns Subdistrict IDs)
• Search International Destination Endpoint: Get international destinations
• Cost Calculation Endpoint: Calculate costs using Subdistrict IDs from search results

Universal Endpoints:

• Waybills Endpoint: Real-time package tracking

Step 4: Understanding Cost Calculation Options

Step-by-Step Method offers 2 calculation levels:

Option A: Calculate by District ID

• Stop at district level in the hierarchy
• Use District ID for cost calculation
• Less precise but faster process

Option B: Calculate by Subdistrict ID

• Continue to subdistrict level in the hierarchy
• Use Subdistrict ID for cost calculation
• More precise location-based pricing

Direct Search Method:

• Only uses Subdistrict ID for calculation
• Search results automatically include detailed location data down to subdistrict level
• More accurate pricing with fewer API calls

Step 5: Make Your First API Request

Choose the example based on your selected method:

Step-by-Step Method Example:

# Get list of provinces first
curl --location 'https://rajaongkir.komerce.id/api/v1/destination/province' \
--header 'key: YOUR_API_KEY'

Direct Search Method Example:

# Search for a city directly (gets Subdistrict IDs)
curl --location 'https://rajaongkir.komerce.id/api/v1/destination/domestic-destination?search=jakarta&limit=5&offset=0' \
--header 'key: YOUR_API_KEY'

Replace YOUR_API_KEY with the key you generated earlier.

Step 6: Handle API Responses

• Successful Response: The API returns a 200 OK status with the requested data.
• Error Response: You'll get an error code (e.g., 400 Bad Request) and a description. Check the error codes for troubleshooting.

Step 7: Calculate Shipping Costs

After getting location IDs from either method:

For Step-by-Step Method:

• Use District ID for general calculation, OR
• Use Subdistrict ID for more precise calculation

For Direct Search Method:

• Use Subdistrict ID from search results

Step 8: Advanced Features

• Waybill Tracking: Get real-time tracking updates for your shipments
• International Shipping: Calculate costs for worldwide destinations
• Multiple Courier Support: Compare rates across different shipping providers

Best Practices

1. Secure Your API Key: Never share your key publicly or include it in client-side code.
2. Use Environment Variables: Store your API key securely in your application environment.
3. Rate Limiting: Be aware of the rate limits based on your subscription tier. Avoid sending excessive requests in a short period.
4. Choose the Right Method: Use Step-by-Step for structured forms, Direct Search for modern UX.
5. Select Appropriate Calculation Level: Use District ID for speed, Subdistrict ID for accuracy.

Which Method Should You Choose?

Method Comparison Summary

Step-by-Step Method:

• ✅ Flexible calculation levels (District or Subdistrict)
• ✅ Familiar dropdown UI pattern
• ✅ Good for guided user experience

Direct Search Method:

• ✅ Fewer API calls needed
• ✅ Modern search-based UX
• ✅ Automatically provides precise Subdistrict IDs
• ✅ Faster development time

Need Help?

If you run into any issues, RajaOngkir provides a support page and community forums.

Start building amazing shipping integrations today with RajaOngkir API V2! 🚀