diff --git a/docs/source/examples.html.md.erb b/docs/source/examples.html.md.erb
index 7b43c4cfa..e403d66ff 100644
--- a/docs/source/examples.html.md.erb
+++ b/docs/source/examples.html.md.erb
@@ -210,11 +210,27 @@ See the documentation about the [placesAutocompleteDataset function](documentati
 
 ### Nearby City Search
 
-**Concepts:** type parameter, aroundLatLngViaIP, aroundPrecision, Places API Client.
+**Concepts:** type parameter, aroundLatLngViaIP, aroundPrecision, programmatic search.
 
 In this section, we will see how you can _emulate_ reverse geocoding to find city closest to a user using the Places API Client.
 
-<%= partial '/partials/examples/reverse-city-search/demo', locals: config[:credentials][:documentation] %>
+<%= partial '/partials/examples/reverse-city-search/demo_places', locals: config[:credentials][:documentation] %>
+
+```html
+<%= partial '/partials/examples/reverse-city-search/code_places', locals: config[:credentials][:placeholder] %>
+```
+
+**Note:** This is not a reverse geocoding API, and it is still bound by the ranking used for search, which means that in some cases large close-by cities can be promoted over a more closely located city.
+
+### Using an API client
+
+In some cases, you may not want to tie your Places search to an input, but rather access it only programmatically.
+
+In these cases, you can use the regular JavaScript API Client, or the api client in your preferred language. You can head to the [API Clients page](api-clients.html) to see which api clients support Places.
+
+For instance, here we will rewrite the previous example using the JS api client instead.
+
+<%= partial '/partials/examples/reverse-city-search/code', locals: config[:credentials][:documentation] %>
 
 ```html
 <%= partial '/partials/examples/reverse-city-search/code', locals: config[:credentials][:placeholder] %>
diff --git a/docs/source/partials/examples/reverse-city-search/_code.html.erb b/docs/source/partials/examples/reverse-city-search/_code.html.erb
index 8e6b52dc4..cb273f9ce 100644
--- a/docs/source/partials/examples/reverse-city-search/_code.html.erb
+++ b/docs/source/partials/examples/reverse-city-search/_code.html.erb
@@ -1,6 +1,6 @@
 <div>
   <strong>Searching around: </strong>
-  <div id="reverse-city"></div>
+  <div id="api-client-reverse-city"></div>
 </div>
 
 <script src="https://cdn.jsdelivr.net/algoliasearch/3/algoliasearch.min.js"></script>
@@ -27,7 +27,7 @@ placesClient.search({
   var country = hits[0].country;
   var formattedCity = locale_names[0] + ', ' + country;
 
-  var infoElt = document.querySelector("#reverse-city");
+  var infoElt = document.querySelector("#api-client-reverse-city");
   infoElt.textContent = formattedCity;
 });
 </script>
\ No newline at end of file
diff --git a/docs/source/partials/examples/reverse-city-search/_code_places.html.erb b/docs/source/partials/examples/reverse-city-search/_code_places.html.erb
new file mode 100644
index 000000000..c559350c8
--- /dev/null
+++ b/docs/source/partials/examples/reverse-city-search/_code_places.html.erb
@@ -0,0 +1,30 @@
+<div>
+  <strong>Searching around: </strong>
+  <input type="search" id="reverse-city" placeholder="What's your favorite city?"></div>
+</div>
+
+<%= javascript_include_tag config[:places_lib_url] %>
+<script>
+var placesAutocomplete = places({
+    appId: '<%= app_id %>',
+    apiKey: '<%= api_key %>',
+    container: document.querySelector('#reverse-city')
+  }).configure({
+    type: 'city',
+    hitsPerPage: 1,
+    aroundLatLngViaIP: true
+  });
+
+placesAutocomplete.search().then(function(suggestions) {
+  if (!suggestions[0]) {
+    return;
+  }
+
+  var name = suggestions[0].name;
+  var country = suggestions[0].country;
+  var formattedCity = locale_names[0] + ', ' + country;
+
+  var infoElt = document.querySelector("#reverse-city");
+  infoElt.value = formattedCity;
+});
+</script>
\ No newline at end of file
diff --git a/docs/source/partials/examples/reverse-city-search/_demo.html.erb b/docs/source/partials/examples/reverse-city-search/_demo.html.erb
deleted file mode 100644
index 12351c494..000000000
--- a/docs/source/partials/examples/reverse-city-search/_demo.html.erb
+++ /dev/null
@@ -1,46 +0,0 @@
-<div>
-<p>When constructing a search UI using InstantSearch, you may want to filter your dataset to only display some of your products based on the distance to the end user. This is usually done using the aroundLatLngViaIP filter, or aroundLatLng filter if you have access to precise geolocation information. However geographical filters are hard to interpret when displayed in raw format, as noone really knows where the coordinates <span id="coords"><code>48.8566, 2.34287</code></span> are.</p>
-
-<p>Using Places, you can do a query to find the city in which your user is located and display that city name instead of a geolocation.</p>
-</div>
-
-<p><strong>Example:</strong></p>
-
-<div>
-  <strong>Searching around: </strong>
-  <div id="reverse-city"></div>
-</div>
-
-<script src="https://cdn.jsdelivr.net/algoliasearch/3/algoliasearch.min.js"></script>
-<script>
-var placesClient = algoliasearch.initPlaces(
-  '<%= app_id %>',
-  '<%= api_key %>'
-);
-
-var preferredLanguage = window.navigator.language.split('-')[0];
-
-placesClient.search({
-  query: '',
-  aroundLatLngViaIP: true,
-  type: 'city',
-  hitsPerPage: 1,
-  language: preferredLanguage,
-}).then(function(results) {
-  var hits = results.hits;
-  if (!hits[0]) {
-    return;
-  }
-  var locale_names = hits[0].locale_names;
-  var country = hits[0].country;
-  var _geoloc = hits[0]._geoloc;
-  var formattedCity = locale_names[0] + ', ' + country;
-
-  var coordElt = document.querySelector("#coords"); 
-  var lat = _geoloc.lat;
-  var lng = _geoloc.lng;
-  coordElt.innerHTML = '<code>' + lat + ', ' + lng + '</code>';
-  var infoElt = document.querySelector("#reverse-city");
-  infoElt.textContent = formattedCity;
-});
-</script>
\ No newline at end of file
diff --git a/docs/source/partials/examples/reverse-city-search/_demo_places.html.erb b/docs/source/partials/examples/reverse-city-search/_demo_places.html.erb
new file mode 100644
index 000000000..bacf0ad59
--- /dev/null
+++ b/docs/source/partials/examples/reverse-city-search/_demo_places.html.erb
@@ -0,0 +1,54 @@
+<div>
+<p>When constructing a search UI using InstantSearch, you may want to filter your dataset to only display some of your products based on the distance to the end user. This is usually done using the aroundLatLngViaIP filter, or aroundLatLng filter if you have access to precise geolocation information. However geographical filters are hard to interpret when displayed in raw format, as noone really knows where the coordinates <span id="coords"><code>48.8566, 2.34287</code></span> are.</p>
+
+<p>Using Places, you can do a query to find the city in which your user is located and display that city name instead of a geolocation.</p>
+</div>
+
+<p><strong>Example:</strong></p>
+
+<div>
+  <strong>Searching around: </strong>
+  <input type="search" id="reverse-city" placeholder="Your favorite city" />
+</div>
+
+<%= javascript_include_tag config[:places_lib_url] %>
+<script>
+var placesAutocomplete = places({
+    appId: '<%= app_id %>',
+    apiKey: '<%= api_key %>',
+    container: document.querySelector('#reverse-city')
+  }).configure({
+    type: 'city',
+    hitsPerPage: 5,
+    aroundLatLngViaIP: true,
+    debug: true
+  });
+
+placesAutocomplete.search().then(function(suggestions) {
+  if (!suggestions[0]) {
+    return;
+  }
+
+  var name = suggestions[0].name;
+  var country = suggestions[0].country;
+  var latlng = suggestions[0].latlng;
+  var formattedCity = name + ', ' + country;
+
+  var coordElt = document.querySelector("#coords");
+  var lat = latlng.lat;
+  var lng = latlng.lng;
+  coordElt.innerHTML = '<code>' + lat + ', ' + lng + '</code>';
+
+  var infoElt = document.querySelector("#reverse-city");
+  infoElt.value = formattedCity;
+});
+
+placesAutocomplete.on('change', (response) => {
+  var suggestion = response.suggestion;
+  var latlng = suggestion.latlng;
+  var coordElt = document.querySelector("#coords");
+  var lat = latlng.lat;
+  var lng = latlng.lng;
+  coordElt.innerHTML = '<code>' + lat + ', ' + lng + '</code>';
+});
+</script>
\ No newline at end of file
diff --git a/src/places.js b/src/places.js
index 69169ad47..291cbf066 100644
--- a/src/places.js
+++ b/src/places.js
@@ -182,6 +182,11 @@ export default function places(options) {
 
   placesInstance.autocomplete = autocompleteInstance;
 
+  placesInstance.search = (query = '') =>
+    new Promise(resolve => {
+      autocompleteDataset.source(query, resolve);
+    });
+
   placesInstance.configure = configuration => {
     const safeConfig = { ...configuration };
 
diff --git a/src/places.test.js b/src/places.test.js
index 8ef943cfa..d81d64c35 100644
--- a/src/places.test.js
+++ b/src/places.test.js
@@ -430,4 +430,26 @@ describe('places', () => {
       language: 'de',
     });
   });
+
+  it('has a search method which calls autocomplete.source', () => {
+    autocomplete.mockClear();
+    const container = document
+      .querySelector('body')
+      .appendChild(document.createElement('input'));
+
+    const searchMock = jest.fn();
+    createAutocompleteDataset.mockImplementation(() => ({
+      source: searchMock,
+      other: 'autocompleteDataset',
+    }));
+
+    const placesInstance = places({
+      container,
+      autocompleteOptions: { option: 'value' },
+    });
+
+    placesInstance.search('some Query');
+
+    expect(searchMock.mock.calls[0][0]).toEqual('some Query');
+  });
 });