The Algolia Places REST API supports HTTPS and is available via the https://places-dsn.algolia.net domain (leveraging our Distributed Search Network infrastructure).
In order to guarantee a very high-availability, we recommend to implement a retry strategy on the following hosts if the https://places-dsn.algolia.net call fails:
https://places-1.algolianet.com,https://places-2.algolianet.com,https://places-3.algolianet.com.To search using the Algolia Places REST API, you need to target the /1/places/query endpoint with a POST request.
1
$ curl -X POST 'https://places-dsn.algolia.net/1/places/query' --data '{"query": "Paris"}'
Note: The relative path prefix /1/ indicates that we are currently using version 1 of the API.
To get an Algolia Places Record using the REST API, you need to target the /1/places/{objectID} endpoint with a GET request.
Replace {objectID} by the objectID you whish to query.
1
$ curl -X GET 'https://places-dsn.algolia.net/1/places/111781_17807753'
Note: The relative path prefix /1/ indicates that we are currently using version 1 of the API.
If you're using the authenticated version of our API (higher rate-limits), you'll need to authenticate yourself. This is done via the following HTTP headers:
X-Algolia-Application-Id,X-Algolia-API-Key.1
2
3
4
$ curl -X POST 'https://places-dsn.algolia.net/1/places/query' \
-H 'X-Algolia-Application-Id: YourApplicationId' \
-H 'X-Algolia-API-Key: YourAPIKey' \
--data '{"query": "Paris"}'
Those are the available query parameters you can use to filter your search results:
| Option | Description |
|---|---|
typeType: string | Restrict the search results to a specific type. Available types:
Default: Search in all types. |
hitsPerPageType: number | Specifies how many results you want to retrieve per search. Default: 20. |
languageType: string | If specified, restrict the search results to a single language. You can pass two letters country codes (ISO 639-1). |
countriesType: string | If specified, restrict the search results to a specific list of comma-separated countries. You can pass two letters country codes (ISO 3166-1). Default: Search on the whole planet. |
aroundLatLngType: string | Force to first search around a specific latitude longitude. The option value must be provided as a string: The default is to search around the location of the user determined via his IP address (geoip). |
aroundLatLngViaIPType: boolean | Whether or not to first search around the geolocation of the user found via his IP address. This is |
aroundRadiusType: number | Radius in meters to search around the latitude/longitutde. Otherwise a default radius is automatically computed given the area density. |
For instance, to search for cities in the US and in France, you would do:
1
2
$ curl -X POST 'https://places-dsn.algolia.net/1/places/query' \
--data '{"query": "Paris", "type": "city", "countries": ["us", "fr"]}'
You can use the regular X-Forwarded-For HTTP header to override the source IP address used to resolve the geo-location of the user. This is particularly useful when you want to use the API from your backend as if it was from your end-users locations.
1
2
3
$ curl -X POST 'https://places-dsn.algolia.net/1/places/query' \
-H 'X-Forwarded-For: 1.2.3.4' \
--data '{"query": "Paris"}'
The API answers is using the JSON format and looks like:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
{
"hits": [{
"objectID": "145746683_7444",
"locale_names": {
"ar": ["باريس"],
"ru": ["Париж"],
"fr": ["Paris", "Lutèce"],
"it": ["Parigi"],
"default": ["Paris"],
"pl": ["Paryż"],
"hu": ["Párizs"],
"ja": ["パリ"],
"nl": ["Parijs"],
"es": ["París"],
"zh": ["巴黎"]
},
"city": {
"default": ["Paris"],
// ... other languages
},
"county": {
"default": ["Paris"],
// ... other languages
},
"administrative": ["Île-de-France"],
"country": {
"default": "France",
// ... other languages
},
"country_code": "fr",
"postcode": ["75000"],
"population": 2243833,
"_geoloc": {
"lat": 48.8564,
"lng": 2.3521
},
"_highlightResult": {
"locale_names": {
"default": [{
"value": "<em>Paris</em>",
"fullyHighlighted": true,
"matchedWords": ["paris"],
"matchLevel": "full"
}]
// [...]
},
"city": {
// [...]
},
"county": {
// [...]
},
"country": {
// [...]
},
"postcode": [
// [...]
],
"administrative": [
// [...]
]
}
}],
"nbHits": 1,
"query": "Paris"
}
| Property | Description |
|---|---|
locale_name | List of names of the place. If no Examples:
|
city | List of the associated city names. If no |
county | List of the associated county names. If no |
administrative | List of associated administrative region names. Examples:
|
country | Associated country name. |
countryCode | Two letters country code (ISO 639-1). |
postcode | List of associated postcodes. |
population | Associated population. |
_geoloc | Associated list of latitude and longitude. Examples:
|
_highlightResult | The associated highlighting information. |
Note: The non-documented attributes of the JSON answer may change, don't rely on them.
The Algolia Places REST API leverages Algolia's Search API, the OpenStreetMap and the GeoNames data.
When you perform an Algolia Places Query:
aroundLatLng query parameter or if your source IP address isn't geo-localized, results will come from all around the world.aroundLatLng query parameter or if your source IP address is geo-localized, results will be composed by: country query parameter will override this behavior, restricting the results to come from a subset of the countries.city and an address are matching, the city will be retrieved first.query doesn't retrieve any results, we fallback on a degraded query strategy: all words are considered optional and we only target cities.
