examples.sh

#!/usr/bin/env bash
# =============================================================================
# MobileAPI.dev - curl Examples
#
# Annotated examples covering every MobileAPI endpoint.
# Requires: curl, jq (optional, for formatted output)
#
# Setup:
#   export MOBILEAPI_KEY="your_api_key_here"
#
# Get a free API key: https://mobileapi.dev/signup/
# Full docs: https://mobileapi.dev/docs/
# =============================================================================

set -euo pipefail

BASE_URL="https://api.mobileapi.dev"

# Check for API key
if [ -z "${MOBILEAPI_KEY:-}" ]; then
    echo "Error: MOBILEAPI_KEY environment variable is not set."
    echo ""
    echo "  export MOBILEAPI_KEY='your_api_key_here'"
    echo ""
    echo "Get a free key at: https://mobileapi.dev/signup/"
    exit 1
fi

# Auth header used in all requests
AUTH="Authorization: Bearer ${MOBILEAPI_KEY}"

# Helper to print section headers
section() {
    echo ""
    echo "=================================================================="
    echo "  $1"
    echo "=================================================================="
    echo ""
}

# Helper: run a curl command, print the command, then the result
run() {
    local description="$1"
    local url="$2"
    echo "# ${description}"
    echo "# curl -s -H \"Authorization: Bearer \$MOBILEAPI_KEY\" \"${url}\""
    echo ""
    curl -s -H "${AUTH}" "${url}" | jq . 2>/dev/null || curl -s -H "${AUTH}" "${url}"
    echo ""
    echo "---"
    echo ""
}


# =============================================================================
section "1. List Devices (paginated)"
# =============================================================================
# Returns a paginated list of all devices in the database.
# Params: page (default 1), limit (max 50)

run "List first 5 devices" \
    "${BASE_URL}/devices/?page=1&limit=5"


# =============================================================================
section "2. Get a Single Device by ID"
# =============================================================================
# Returns full details for one device, including a base64 thumbnail.

run "Get device with ID 1" \
    "${BASE_URL}/devices/1/"


# =============================================================================
section "3. Search Devices (fuzzy matching)"
# =============================================================================
# Search by name with typo tolerance. Returns match_certainty (0-100%)
# and match_type for each result.
#
# You can also search by model_number instead of name.
# Add exact=true for strict matching only.

run "Search for 'Samsung Galaxy S25'" \
    "${BASE_URL}/devices/search/?name=samsung+galaxy+s25&limit=5"

# Fuzzy matching handles typos:
run "Fuzzy search with typo: 'samsng galaxi'" \
    "${BASE_URL}/devices/search/?name=samsng+galaxi&limit=3"


# =============================================================================
section "4. Autocomplete (type-ahead)"
# =============================================================================
# Returns quick suggestions as the user types.
# Great for search-as-you-type UIs.

run "Autocomplete for 'iph'" \
    "${BASE_URL}/devices/autocomplete/?name=iph&limit=5"


# =============================================================================
section "5. Filter by Manufacturer"
# =============================================================================
# List all devices from a specific brand.

run "Apple devices (first 5)" \
    "${BASE_URL}/devices/by-manufacturer/?manufacturer=Apple&page=1&limit=5"


# =============================================================================
section "6. Filter by Release Year"
# =============================================================================
# List devices released in a specific year.

run "Devices released in 2025 (first 5)" \
    "${BASE_URL}/devices/by-year/?year=2025&page=1&limit=5"


# =============================================================================
section "7. Filter by Device Type"
# =============================================================================
# Types: phone, tablet, laptop, wearable, other

run "Tablets (first 5)" \
    "${BASE_URL}/devices/by-type/?type=tablet&page=1&limit=5"


# =============================================================================
section "8. Device Specifications (individual categories)"
# =============================================================================
# Available specs: network, body, display, platform, memory,
#   cameras, sound, communications, features, battery, miscellaneous

run "Display specs for device 1" \
    "${BASE_URL}/devices/1/display/"

run "Battery specs for device 1" \
    "${BASE_URL}/devices/1/battery/"

run "Camera specs for device 1" \
    "${BASE_URL}/devices/1/cameras/"

run "Platform specs for device 1" \
    "${BASE_URL}/devices/1/platform/"

run "Memory specs for device 1" \
    "${BASE_URL}/devices/1/memory/"


# =============================================================================
section "9. Device Images"
# =============================================================================
# Get image gallery metadata for a device.
# Note: Fetching full-resolution images consumes image credits.

run "Image gallery for device 1" \
    "${BASE_URL}/devices/1/images/"

# The primary image endpoint returns binary image data:
echo "# Primary device image (binary -- save to file):"
echo "# curl -s -H \"Authorization: Bearer \$MOBILEAPI_KEY\" \\"
echo "#   \"${BASE_URL}/devices/1/image/\" -o device.jpg"
echo ""
echo "---"
echo ""


# =============================================================================
section "10. Manufacturers"
# =============================================================================
# List all brands or get details for a specific manufacturer.

run "List manufacturers (first 10)" \
    "${BASE_URL}/manufacturers/?page=1&limit=10"


# =============================================================================
section "11. Rate Limit Headers"
# =============================================================================
# Every response includes rate limit headers.
# Use -i flag to see them.

echo "# Check rate limit headers with -i flag:"
echo "# curl -s -i -H \"Authorization: Bearer \$MOBILEAPI_KEY\" \"${BASE_URL}/devices/?limit=1\""
echo ""
echo "# Response headers include:"
echo "#   X-RateLimit-Limit: 200        (total allowed per window)"
echo "#   X-RateLimit-Remaining: 195    (remaining in current window)"
echo "#   X-RateLimit-Reset: 1700000000 (unix timestamp for reset)"
echo ""
echo "---"
echo ""


# =============================================================================
section "12. Authentication Methods"
# =============================================================================
# MobileAPI supports three authentication methods:

echo "# Method 1: Bearer token (recommended)"
echo "# curl -s -H \"Authorization: Bearer \$MOBILEAPI_KEY\" \"${BASE_URL}/devices/?limit=1\""
echo ""
echo "# Method 2: Token header"
echo "# curl -s -H \"Authorization: Token \$MOBILEAPI_KEY\" \"${BASE_URL}/devices/?limit=1\""
echo ""
echo "# Method 3: Query parameter"
echo "# curl -s \"${BASE_URL}/devices/?limit=1&key=\$MOBILEAPI_KEY\""
echo ""
echo "---"
echo ""


# =============================================================================
section "Tips"
# =============================================================================

echo "# Pipe through jq for formatted output:"
echo "#   curl -s -H \"Authorization: Bearer \$MOBILEAPI_KEY\" \\"
echo "#     \"${BASE_URL}/devices/search/?name=pixel+9\" | jq ."
echo ""
echo "# Extract just device names from search results:"
echo "#   curl -s -H \"Authorization: Bearer \$MOBILEAPI_KEY\" \\"
echo "#     \"${BASE_URL}/devices/search/?name=pixel+9\" | jq '.results[].name'"
echo ""
echo "# Count total devices from a manufacturer:"
echo "#   curl -s -H \"Authorization: Bearer \$MOBILEAPI_KEY\" \\"
echo "#     \"${BASE_URL}/devices/by-manufacturer/?manufacturer=Samsung&limit=1\" | jq '.total'"
echo ""
echo "# Save device image to a file:"
echo "#   curl -s -H \"Authorization: Bearer \$MOBILEAPI_KEY\" \\"
echo "#     \"${BASE_URL}/devices/1/image/\" -o device.jpg"
echo ""

echo "Done! For full documentation, visit: https://mobileapi.dev/docs/"
echo "Get your free API key: https://mobileapi.dev/signup/"