Q:

How to get the distance between two objects in the game engine?

So far I could only find the method to get the current position of the objects. I think there is a method that returns the distance between them.

A:

You can use mathutils.Vector locations
import bge

scene = bge.logic.getCurrentScene()
# the object the sensor is connected to
owner = bge.logic.getCurrentController().owner
# the other object you want to get the distance to
obj2 = scene.objects['obj_name']
length = (owner.worldPosition - obj2.worldPosition).length

print(length)

This allows for easier manipulation, so for example if you only want to measure distance on a map (without taking altitude into account) you can do.
length = (owner.worldPosition.xy - obj2.worldPosition.xy).length

A:

That would be getDistanceTo. It will calculate and return the distance between two objects from their origins.
import bge

scene = bge.logic.getCurrentScene()
# the object the sensor is connected to
owner = bge.logic.getCurrentController().owner
# the other object you want to get the distance to
obj2 = scene.objects['obj_name']
length = owner.getDistanceTo(obj2)

print(length)

A:

I am not sure how you plan on telling blender which two objects. Assuming they are both selected.
import bpy
from math import sqrt

def get_distance():
    """
    return: float. Distance of the two objects
    Must select two objects
    """
    l = []  # we store the loacation vector of each object
    for item in bpy.context.selected_objects:
        l.append(item.location)

    distance = sqrt( (l[0][0] - l[1][0])**2 + (l[0][1] - l[1][1])**2 + (l[0][2] - l[1][2])**2)
    print(distance)  # print distance to console, DEBUG
    return distance

get_distance()

