📍 Send Location Messages

Share precise location coordinates with WhatsApp contacts using the Whatspie API with support for custom location names and interactive maps.

🗺️ Interactive Location Sharing

Send precise GPS coordinates with automatic map preview, custom location names, and one-tap navigation for recipients.

🌐 Endpoint

POST https://api.whatspie.com/messages

🔐 Authentication

Bearer token required with proper JSON content headers.

📋 Request Parameters

Parameter	Type	Required	Description
`device`	string	✅	Your registered WhatsApp device number
`receiver`	string	✅	Recipient's phone number (international format)
`type`	string	✅	Message type: `"location"` for location messages
`params`	object	✅	Message parameters containing location data
`params.location`	object	✅	Location object with coordinates
`params.location.degreesLatitude`	number	✅	Location latitude coordinate (-90 to 90)
`params.location.degreesLongitude`	number	✅	Location longitude coordinate (-180 to 180)
`simulate_typing`	integer	❌	Show typing indicator: `1` (yes) or `0` (no)

🗺️ Coordinate System

Whatspie API uses the WGS84 coordinate system (same as GPS):

🚀 Request Examples

Basic Location Message

curl -X POST "https://api.whatspie.com/messages" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "device": "6281234567890",
    "receiver": "6289876543210",
    "type": "location",
    "params": {
      "location": {
        "degreesLatitude": -6.2088,
        "degreesLongitude": 106.8456
      }
    },
    "simulate_typing": 1
  }'

Location with Custom Name

curl -X POST "https://api.whatspie.com/messages" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "device": "6281234567890",
    "receiver": "6289876543210",
    "type": "location",
    "params": {
      "location": {
        "degreesLatitude": -6.2088,
        "degreesLongitude": 106.8456
      }
    },
    "simulate_typing": 1
  }'

Business Location

curl -X POST "https://api.whatspie.com/messages" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "device": "6281234567890",
    "receiver": "6289876543210", 
    "type": "location",
    "latitude": 37.7749,
    "longitude": -122.4194,
    "location_name": "🏢 Our Office - 123 Business St, San Francisco, CA",
    "simulate_typing": 1
  }'

📊 Response Format

Success Response

{
  "code": 200,
  "message": "Location sent successfully",
  "data": {
    "id": "msg_location_12345",
    "status": "pending",
    "type": "location",
    "coordinates": {
      "latitude": -6.2088,
      "longitude": 106.8456
    },
    "location_name": "Monas - National Monument Jakarta",
    "timestamp": "2024-12-20T10:30:00Z"
  }
}

Error Response - Invalid Coordinates

{
  "code": 400,
  "message": "Invalid coordinates",
  "error": "Latitude must be between -90 and 90, longitude must be between -180 and 180"
}

🌟 Advanced Examples

Location with Address Lookup

// Reverse geocoding to get address from coordinates
async function sendLocationWithAddress(token, device, receiver, latitude, longitude) {
  try {
    // Get address from coordinates (using a geocoding service)
    const address = await reverseGeocode(latitude, longitude);
    
    const locationName = `📍 ${address.name}\n${address.street}, ${address.city}`;
    
    return await sendLocationMessage(
      token,
      device, 
      receiver, 
      latitude, 
      longitude, 
      locationName
    );
  } catch (error) {
    // Fallback to coordinates only if address lookup fails
    return await sendLocationMessage(token, device, receiver, latitude, longitude);
  }
}

// Mock reverse geocoding function
async function reverseGeocode(lat, lng) {
  // In real implementation, use Google Maps API, OpenStreetMap, etc.
  return {
    name: "Business Center",
    street: "Jl. Sudirman No. 123",
    city: "Jakarta"
  };
}

async function sendMultipleLocations(token, device, receiver, locations) {
  const results = [];
  
  for (const location of locations) {
    try {
      const result = await sendLocationMessage(
        token,
        device,
        receiver,
        location.latitude,
        location.longitude,
        location.name
      );
      
      results.push({
        location: location.name,
        success: true,
        messageId: result.data.id
      });
      
      // Delay between messages to avoid rate limiting
      await new Promise(resolve => setTimeout(resolve, 2000));
      
    } catch (error) {
      results.push({
        location: location.name,
        success: false,
        error: error.message
      });
    }
  }
  
  return results;
}

// Usage
const touristSpots = [
  { name: '🗿 Monas Jakarta', latitude: -6.1751, longitude: 106.8650 },
  { name: '🏛️ National Museum', latitude: -6.1717, longitude: 106.8219 },
  { name: '🌊 Ancol Beach', latitude: -6.1260, longitude: 106.8421 }
];

sendMultipleLocations('YOUR_API_TOKEN', '6281234567890', '6289876543210', touristSpots);

Location with Custom Map Preview

// Generate custom map URL for location preview
function generateMapPreview(latitude, longitude, zoom = 15) {
  return `https://maps.googleapis.com/maps/api/staticmap?center=${latitude},${longitude}&zoom=${zoom}&size=400x300&maptype=roadmap&markers=color:red%7C${latitude},${longitude}&key=YOUR_MAPS_API_KEY`;
}

async function sendLocationWithPreview(token, device, receiver, latitude, longitude, locationName) {
  // First send the location
  const locationResult = await sendLocationMessage(
    token, 
    device, 
    receiver, 
    latitude, 
    longitude, 
    locationName
  );
  
  // Then send a map preview image (optional)
  const mapUrl = generateMapPreview(latitude, longitude);
  
  const imageResult = await sendImageMessage(
    token,
    device,
    receiver,
    mapUrl,
    '🗺️ Map Preview'
  );
  
  return {
    location: locationResult,
    preview: imageResult
  };
}

💡 Best Practices

1. Coordinate Validation

function validateCoordinates(latitude, longitude) {
  const lat = parseFloat(latitude);
  const lng = parseFloat(longitude);
  
  if (isNaN(lat) || lat < -90 || lat > 90) {
    throw new Error('Invalid latitude. Must be between -90 and 90');
  }
  
  if (isNaN(lng) || lng < -180 || lng > 180) {
    throw new Error('Invalid longitude. Must be between -180 and 180');
  }
  
  return { latitude: lat, longitude: lng };
}

2. Location Name Formatting

function formatLocationName(name, address = null, category = null) {
  let formattedName = '';
  
  // Add category emoji
  const categoryEmojis = {
    'restaurant': '🍽️',
    'hotel': '🏨',
    'office': '🏢',
    'hospital': '🏥',
    'school': '🏫',
    'shopping': '🛍️',
    'gas_station': '⛽',
    'bank': '🏦'
  };
  
  if (category && categoryEmojis[category]) {
    formattedName += categoryEmojis[category] + ' ';
  } else {
    formattedName += '📍 ';
  }
  
  formattedName += name;
  
  if (address) {
    formattedName += '\n' + address;
  }
  
  return formattedName;
}

// Usage
const locationName = formatLocationName(
  'Central Park Mall',
  'Jl. Letjen S. Parman, Jakarta Barat',
  'shopping'
);
// Result: "🛍️ Central Park Mall\nJl. Letjen S. Parman, Jakarta Barat"

3. Distance Calculation

function calculateDistance(lat1, lon1, lat2, lon2) {
  const R = 6371; // Earth's radius in kilometers
  const dLat = (lat2 - lat1) * Math.PI / 180;
  const dLon = (lon2 - lon1) * Math.PI / 180;
  
  const a = Math.sin(dLat / 2) * Math.sin(dLat / 2) +
            Math.cos(lat1 * Math.PI / 180) * Math.cos(lat2 * Math.PI / 180) *
            Math.sin(dLon / 2) * Math.sin(dLon / 2);
  
  const c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a));
  const distance = R * c; // Distance in kilometers
  
  return Math.round(distance * 100) / 100; // Round to 2 decimal places
}

// Usage
const distance = calculateDistance(-6.2088, 106.8456, -6.1751, 106.8650);
console.log(`Distance: ${distance} km`);

🌍 Common Locations

Famous Landmarks

const landmarks = {
  // Indonesia
  monas: { lat: -6.1751, lng: 106.8650, name: '🗿 Monas - National Monument' },
  borobudur: { lat: -7.6079, lng: 110.2038, name: '🏛️ Borobudur Temple' },
  
  // International
  eiffel_tower: { lat: 48.8584, lng: 2.2945, name: '🗼 Eiffel Tower, Paris' },
  statue_liberty: { lat: 40.6892, lng: -74.0445, name: '🗽 Statue of Liberty, NYC' },
  big_ben: { lat: 51.4994, lng: -0.1245, name: '🕰️ Big Ben, London' }
};

// Send landmark location
await sendLocationMessage(
  'YOUR_API_TOKEN',
  '6281234567890', 
  '6289876543210',
  landmarks.monas.lat,
  landmarks.monas.lng,
  landmarks.monas.name
);

⚠️ Limitations

Coordinate precision: Up to 6 decimal places for accuracy
Location name: Maximum 100 characters
Map providers: Location display depends on recipient's map app
Real-time tracking: Static location only, no live tracking
Offline access: Recipients need internet to view map details

Send Text Messages - For location descriptions
Send Image Messages - For map screenshots
Get Message Status - Check delivery status

🗺️ Map Integration Services

For enhanced location features, consider integrating:

Google Maps API - Address lookup and static maps
OpenStreetMap - Open source mapping
Mapbox - Custom map styling
Here Maps - Enterprise mapping solutions

🗺️ Interactive Location Sharing

🌐 Endpoint​

🔐 Authentication​

📋 Request Parameters​

🗺️ Coordinate System​

🚀 Request Examples​

Basic Location Message​

Location with Custom Name​

Business Location​

📊 Response Format​

Success Response​

Error Response - Invalid Coordinates​

🌟 Advanced Examples​

Location with Address Lookup​

Batch Location Sharing​

Location with Custom Map Preview​

💡 Best Practices​

1. Coordinate Validation​

2. Location Name Formatting​

3. Distance Calculation​

🌍 Common Locations​

Famous Landmarks​

⚠️ Limitations​

🔗 Related Endpoints​

🗺️ Map Integration Services​