Places API

The Places API provides comprehensive location search, geocoding, and place information capabilities.

Overview

The Places API includes the following features:

Autocomplete - Real-time place suggestions as users type
Geocoding - Convert addresses to coordinates
Reverse Geocoding - Convert coordinates to addresses
Place Details - Get detailed information about places
Nearby Search - Find places near a location
Text Search - Search for places using text queries
Address Validation - Verify and standardize addresses
Place Photos - Access place images

Autocomplete

Get place suggestions as users type.

Basic Usage

const results = await client.places.autocomplete('Koramangala, Bangalore');

With Options

const results = await client.places.autocomplete('Bangalore', {
    location: '12.93,77.61',  // Bias results to this location
    radius: 5000,             // Search radius in meters
    language: 'en',           // Language preference
    types: 'city',            // Filter by place type
    strictbounds: true        // Strict boundary filtering
});

Parameters

Parameter	Type	Required	Description
`input`	string	Yes	The text input for autocomplete
`options.location`	string	No	Center point for biasing results (lat,lng)
`options.radius`	number	No	Search radius in meters
`options.language`	string	No	Language code (e.g., 'en', 'hi')
`options.types`	string	No	Filter by place type
`options.strictbounds`	boolean	No	Enable strict boundary filtering

Response Example

{
    status: "OK",
    predictions: [
        {
            description: "Koramangala, Bengaluru, Karnataka, India",
            place_id: "ola-platform:5000039498427",
            types: ["neighborhood"],
            matched_substrings: [{ length: 11, offset: 0 }]
        }
    ]
}

Geocoding

Convert an address into geographic coordinates.

Basic Usage

const result = await client.places.geocode('Taj Mahal, Mumbai');

With Language

const result = await client.places.geocode('New Delhi', 'en');

Parameters

Parameter	Type	Required	Description
`address`	string	Yes	The address to geocode
`language`	string	No	Language code for results

Response Example

{
    status: "OK",
    results: [
        {
            formatted_address: "Taj Mahal, Mumbai, Maharashtra, India",
            geometry: {
                location: {
                    lat: 19.017614,
                    lng: 72.856164
                }
            },
            place_id: "ola-platform:5000039498427"
        }
    ]
}

Reverse Geocoding

Convert coordinates into a human-readable address.

Basic Usage

const result = await client.places.reverseGeocode(26.115103, 91.703239);

With Language

const result = await client.places.reverseGeocode(12.9716, 77.5946, 'en');

Parameters

Parameter	Type	Required	Description
`lat`	number	Yes	Latitude
`lng`	number	Yes	Longitude
`language`	string	No	Language code for results

Response Example

{
    status: "OK",
    results: [
        {
            formatted_address: "Guwahati, Assam, India",
            address_components: [
                { long_name: "Guwahati", short_name: "Guwahati", types: ["locality"] },
                { long_name: "Assam", short_name: "AS", types: ["administrative_area_level_1"] },
                { long_name: "India", short_name: "IN", types: ["country"] }
            ],
            geometry: {
                location: { lat: 26.115103, lng: 91.703239 }
            }
        }
    ]
}

Place Details

Get detailed information about a specific place.

Basic Place Details

const details = await client.places.placeDetails('ola-platform:5000039498427');

With Language

const details = await client.places.placeDetails('ola-platform:5000039498427', 'en');

Advanced Place Details

Get more comprehensive information:

const details = await client.places.placeDetailsAdvanced('ola-platform:5000039498427');

Parameters

Parameter	Type	Required	Description
`placeId`	string	Yes	The place ID from autocomplete or search
`language`	string	No	Language code for results

Response Example

{
    status: "OK",
    result: {
        name: "Phoenix Marketcity",
        formatted_address: "Mahadevpura, Bengaluru, Karnataka 560048, India",
        geometry: {
            location: { lat: 12.993103, lng: 77.543326 }
        },
        phone_number: "+91 80 4977 4000",
        website: "https://www.phoenixmarketcity.com/bangalore",
        rating: 4.5,
        user_ratings_total: 15234,
        opening_hours: {
            open_now: true,
            weekday_text: ["Monday: 10:00 AM – 10:00 PM", ...]
        },
        photos: [{ photo_reference: "photo_ref_123", width: 4032, height: 3024 }]
    }
}

Nearby Search

Find places near a specific location.

Basic Nearby Search

const results = await client.places.nearbySearch('12.93,77.61', {
    types: 'restaurant',
    radius: 1000,
    language: 'en'
});

Advanced Nearby Search

const results = await client.places.nearbySearchAdvanced('12.93,77.61', {
    types: 'cafe',
    radius: 500,
    rankBy: 'prominence',
    limit: 10
});

Parameters

Parameter	Type	Required	Description
`location`	string	Yes	Center point (lat,lng format)
`options.types`	string	No	Filter by place type
`options.radius`	number	No	Search radius in meters
`options.language`	string	No	Language code
`options.rankBy`	string	No	Ranking method ('prominence' or 'distance')
`options.limit`	number	No	Maximum number of results

Common Place Types

restaurant - Restaurants
cafe - Cafes and coffee shops
hotel - Hotels and lodging
hospital - Hospitals
school - Schools and educational institutions
bank - Banks and ATMs
gas_station - Fuel stations
shopping_mall - Shopping centers

Text Search

Search for places using free-text queries.

Basic Usage

const results = await client.places.textSearch('Cafes in Koramangala');

With Filters

const results = await client.places.textSearch('Restaurants', {
    location: '12.93,77.61',
    radius: 2000,
    types: 'restaurant',
    size: 10
});

Parameters

Parameter	Type	Required	Description
`input`	string	Yes	The search query
`options.location`	string	No	Center point for biasing
`options.radius`	number	No	Search radius in meters
`options.types`	string	No	Filter by place type
`options.size`	number	No	Maximum number of results

Address Validation

Validate and standardize addresses.

Basic Usage

const validation = await client.places.addressValidation('7, Lok Kalyan Marg, New Delhi');

Response Example

{
    status: "OK",
    result: {
        is_valid: true,
        original_address: "7, Lok Kalyan Marg, New Delhi",
        standardized_address: "7, Lok Kalyan Marg, New Delhi, Delhi 110011, India",
        confidence: 'high',
        corrections: []
    }
}

Place Photos

Access photos associated with places.

Basic Usage

const photo = await client.places.photo('photo_reference_id');

Getting Photo URL

The photo endpoint returns the actual image data. To get a URL:

// The SDK handles authentication automatically
const photoData = await client.places.photo('photo_reference_id');
// Use the returned data directly or convert to URL

Error Handling

Handle errors gracefully:

try {
    const results = await client.places.autocomplete('Bangalore');
    console.log(results);
} catch (error) {
    if (error.message.includes('API key')) {
        console.error('Authentication error:', error.message);
    } else if (error.message.includes('403')) {
        console.error('Permission denied:', error.message);
    } else {
        console.error('Places API error:', error.message);
    }
}

Best Practices

1. Cache Results

Cache autocomplete and place details to reduce API calls:

const cache = new Map();

async function getCachedPlaceDetails(placeId) {
    if (cache.has(placeId)) {
        return cache.get(placeId);
    }
    
    const details = await client.places.placeDetails(placeId);
    cache.set(placeId, details);
    return details;
}

2. Debounce User Input

Debounce autocomplete requests:

const debounce = (fn, delay) => {
    let timeout;
    return (...args) => {
        clearTimeout(timeout);
        timeout = setTimeout(() => fn(...args), delay);
    };
};

const searchPlaces = debounce(async (query) => {
    const results = await client.places.autocomplete(query);
    displayResults(results);
}, 300);

3. Use Location Bias

Bias results to user's current location:

const userLocation = '12.9716,77.5946'; // User's current location
const results = await client.places.autocomplete('Restaurant', {
    location: userLocation,
    radius: 5000
});

Complete Example

Here's a complete example of a place search feature:

const OlaMapsClient = require('ola-map-sdk');
const client = new OlaMapsClient(process.env.OLA_MAPS_API_KEY);

async function findNearbyRestaurants(location, radius = 1000) {
    try {
        // Search for nearby restaurants
        const restaurants = await client.places.nearbySearch(location, {
            types: 'restaurant',
            radius: radius,
            language: 'en'
        });
        
        // Get details for top 3 results
        const topRestaurants = restaurants.results.slice(0, 3);
        const detailsPromises = topRestaurants.map(r => 
            client.places.placeDetails(r.place_id)
        );
        
        const detailedRestaurants = await Promise.all(detailsPromises);
        
        return detailedRestaurants.map(d => ({
            name: d.result.name,
            address: d.result.formatted_address,
            rating: d.result.rating,
            phone: d.result.phone_number,
            location: d.result.geometry.location
        }));
        
    } catch (error) {
        console.error('Error finding restaurants:', error);
        throw error;
    }
}

// Usage
findNearbyRestaurants('12.93,77.61', 2000)
    .then(restaurants => console.log(restaurants))
    .catch(console.error);

Next Steps

Learn about Routing API for directions
Explore Map Display to show results on a map
Check Examples for more use cases

Places API

On this page