Browse
The /browse
endpoint provides a structured search by filtering items by category and name at a given geo-position in a radius of 250km. Items returned are places, streets or localities, ranked by increasing distance.
Location context and geographic filter
/browse
returns HERE Geocoding and Search indices data at am maximum distance of 250km from a search center. The Search center is defined by the geo-position specified in the input query parameter at
. Items distances are calculated with respect to this search center.
Additionally to the implicit filter of 250km around the search center, /browse
supports 2 additional geographic filters through the query parameter in
:
- a circle through the
in
parameter type circle
- a bounding box through the
in
parameter type bbox
- a list of upper-case ISO 3166-1 alpha-3 country codes through the
in
parameter type countryCode
Note that HERE Geocoding and Search supports the country group XEA
, equivalent to the list of country codes AUT, BEL, BGR, HRV, CYP, CZE, DNK, EST, FIN, FRA, DEU, GRC, HUN, IRL, ITA, LVA, LTU, LUX, MLT, NLD, POL, PRT, ROU, SVK, SVN, ESP, SWE
More details are to be found in the API Reference.
The list of allowed at
and in
combinations on /browse
is:
at
-
at
with in=countryCode
-
at
with in=circle
-
at
with in=circle
and in=countryCode
-
at
with in=bbox
-
at
with in=bbox
and in=countryCode
Multigranular category filter
/browse
allows you to retrieve places at a given position for a specific HERE Places category or cuisine.
Multiple values are supported, provided they are separated by a comma. /browse
returns places with at least one of the queried categories. Additionally, the 3 levels of Places categories are supported, for customers needing to retrieve places of a more general category.
/browse
also allows customers to filter results using HERE Places categories at any of their 3 levels:
- level 3 for fine grained categories (ex:
100-1000-0002
for fine dining places), - level 2 for intermediate granularity (ex:
100-1000
for restaurant places) or - level 1 for a high level (ex:
100
for places where you can eat and drink)
For example, an application in a car or on a cell-phone would expose an icon representing a gas-station, and use the category id 700-7600-0000,700-7600-0116
as value for the categories
parameter of a /browse
query:
GET https://browse.search.hereapi.com/v1/
browse
?at=-23.000813,-43.351629
&limit=2
&categories=100-1100,200-2000-0011,100-1000
Bearer [your token]
The expected result for this query would be the following:
{
"items": [
{
"title": "Mirilli e Elias",
"id": "here:pds:place:076xjxn4-bd00422cd7cc0293789ade509aeaef55",
"resultType": "place",
"address": {
"label": "Mirilli e Elias, Avenida das Américas, 3757, Barra da Tijuca, Rio de Janeiro - RJ, 22631-003, Brasil",
"countryCode": "BRA",
"countryName": "Brasil",
"stateCode": "RJ",
"state": "Rio de Janeiro",
"city": "Rio de Janeiro",
"district": "Barra da Tijuca",
"street": "Avenida das Américas",
"postalCode": "22631-003",
"houseNumber": "3757"
},
"position": { "lat": -23.00052, "lng": -43.35129 },
"access": [{ "lat": -23.0004, "lng": -43.35129 }],
"distance": 47,
"categories": [
{ "id": "600-6000-0061", "name": "Loja de Conveniência", "primary": true },
{ "id": "100-1000-0000", "name": "Restaurante" }
],
"contacts": [{ "phone": [{ "value": "+552124312897" }] }]
},
{
"title": "Esplanada da Barra",
"id": "here:pds:place:076jx7ps-200a9cce1dae03cb345916e43ea2252b",
"resultType": "place",
"address": {
"label": "Esplanada da Barra, Avenida das Américas, 3939, Barra da Tijuca, Rio de Janeiro - RJ, 22631-003, Brasil",
"countryCode": "BRA",
"countryName": "Brasil",
"stateCode": "RJ",
"state": "Rio de Janeiro",
"city": "Rio de Janeiro",
"district": "Barra da Tijuca",
"street": "Avenida das Américas",
"postalCode": "22631-003",
"houseNumber": "3939"
},
"position": { "lat": -23.00067, "lng": -43.35246 },
"access": [{ "lat": -23.00039, "lng": -43.35246 }],
"distance": 86,
"categories": [
{ "id": "600-6100-0062", "name": "Centro comercial", "primary": true },
{ "id": "100-1000-0000", "name": "Restaurante" },
{ "id": "100-1000-0001", "name": "Restaurante informal" },
{ "id": "700-7400-0145", "name": "Agência imobiliária" }
],
"references": [
{ "supplier": { "id": "core" }, "id": "1161604855" },
{ "supplier": { "id": "yelp" }, "id": "gGIMGCpXo-_q3hNqEGZzsQ" },
{ "supplier": { "id": "yelp" }, "id": "o84mcglVLsV6wJ9RdeZ_-g" }
],
"foodTypes": [{ "id": "406-000", "name": "Brasileira", "primary": true }],
"contacts": [
{
"phone": [{ "value": "+552124313092" }, { "value": "+552197997461" }],
"www": [
{ "value": "http://www.esplanadadabarra.com.br" },
{ "value": "http://www.esplanadadabarra.com.br/" },
{ "value": "http://www.facebook.com.br" }
]
}
],
"openingHours": [
{
"text": ["Mon-Fri: 08:00 - 15:00"],
"isOpen": true,
"structured": [{ "start": "T080000", "duration": "PT07H00M", "recurrence": "FREQ:DAILY;BYDAY:MO,TU,WE,TH,FR" }]
}
]
}
]
}
A mobile phone application for tourists could use the combination of
- historical monuments (
300-3000-0025
) and museums (300-3100
) - shopping malls (
600-6100-0062
) - parks (
550-5510-0202
) and leisure places (500-5520
)
So that a query from a position in Rome, Italy would look like:
GET https://browse.search.hereapi.com/v1/
browse
?at=41.93088,12.46803
&limit=5
&categories=300-3000-0025,300-3100,550-5510-0202,500-5520,600-6100-0062
Bearer [your token]
The expected result for this query would be:
{
"items": [
{
"title": "Maxxi - Museo Nazionale delle Arti del XXI Secolo",
"id": "here:pds:place:380sr2ye-3f8bfb611d1640e88a8577457c00b118",
"resultType": "place",
"categories": [
{ "id": "300-3100-0029", "name": "Museo delle arti", "primary": true },
{ "id": "200-2100-0019", "name": "Cinema" },
{ "id": "300-3000-0000", "name": "Punto di riferimento o attrazione" },
{ "id": "300-3000-0024", "name": "Galleria" },
{ "id": "300-3000-0025", "name": "Monumento storico" },
{ "id": "300-3100-0000", "name": "Museo" },
{ "id": "900-9300-0221", "name": "Edificio residenziale" }
],
...
},
{
"title": "Palazzetto dello Sport",
"id": "here:pds:place:380sr2ye-90260c572b6444c78b2fc9aa5d5ae4bb",
"categories": [
{ "id": "800-8600-0180", "name": "Complesso sportivo o stadio", "primary": true },
{ "id": "300-3000-0025", "name": "Monumento storico" },
{ "id": "800-8600-0000", "name": "Struttura sportiva" },
{ "id": "800-8600-0197", "name": "Attività Sportive" },
{ "id": "900-9300-0221", "name": "Edificio residenziale" }
],
...
},
{
"title": "Stadio Flaminio",
"id": "here:pds:place:380sr2ye-f9b444880b5b4148acfde15882e4ddf8",
"categories": [
{ "id": "800-8600-0180", "name": "Complesso sportivo o stadio", "primary": true },
{ "id": "200-2000-0015", "name": "Intrattenimento o musica dal vivo" },
{ "id": "300-3000-0025", "name": "Monumento storico" },
{ "id": "900-9300-0221", "name": "Edificio residenziale" }
],
...
},
{
"title": "Villaggio Olimpico",
"id": "here:pds:place:380sr2ye-26b632e3831f41128106c331850d7ff3",
"categories": [
{ "id": "600-6400-0070", "name": "Farmacia", "primary": true },
{ "id": "300-3000-0025", "name": "Monumento storico" },
{ "id": "600-6400-0000", "name": "Farmacia o parafarmacia" },
{ "id": "700-7200-0272", "name": "Assistenza sanitaria e servizi di supporto" }
],
...
},
{
"title": "Auditorium Parco della Musica",
"id": "here:pds:place:380sr2ye-2cbef7afec4e4e3b84db58ce8ee2d6d2",
"categories": [
{ "id": "200-2200-0020", "name": "Teatro", "primary": true },
{ "id": "200-2000-0015", "name": "Intrattenimento o musica dal vivo" },
{ "id": "200-2100-0019", "name": "Cinema" },
{ "id": "200-2200-0000", "name": "Teatro, musica e cultura" },
{ "id": "300-3000-0000", "name": "Punto di riferimento o attrazione" },
{ "id": "300-3000-0025", "name": "Monumento storico" },
{ "id": "800-8700-0296", "name": "Club house" },
{ "id": "900-9300-0221", "name": "Edificio residenziale" }
],
...
}
]
}
Category negative filter
/browse
also allows you to retrieve places that do not have specific categories. For this an exclamation mark ("!") is necessary in front of the category ID. Negated categories and regular categories can be mixed into the same categories
value. Negated categories have precedence over regular ones.
For example, to retrieve all restaurants except fast-food restaurants, an application would add to Browse queries categories=100-1000,!100-1000-0009
.
Name filter
An additional way to filter locations is to use a name
filter. Such a filter is most useful as a complement of a category filter, but can be used solely too.
More specifically, /browse
only returns items for which each word in the name
parameter exactly matches at least one word of the result title.
For example, a cell-phone application would expose an icon representing Petrobras gas-stations, and use the category id 700-7600-0000,700-7600-0116
as value for the categories
parameter together with a name
parameter set to "petrobras":
GET https://browse.search.hereapi.com/v1/
browse
?at=-23.000813,-43.351629
&limit=2
&categories=700-7600-0000,700-7600-0116
&name=Petrobras
Bearer [your token]
The expected result for this query would be the following:
{
"items": [
{
"title": "Petrobras",
"id": "here:pds:place:07675cjj-15f8bcd7e0d544758df31a6562d37a30",
"resultType": "place",
"address": {
"label": "Petrobras, Avenida das Américas, 3757, Barra da Tijuca, Rio de Janeiro - RJ, 22631-003, Brasil",
"countryCode": "BRA",
"countryName": "Brasil",
"stateCode": "RJ",
"state": "Rio de Janeiro",
"city": "Rio de Janeiro",
"district": "Barra da Tijuca",
"street": "Avenida das Américas",
"postalCode": "22631-003",
"houseNumber": "3757"
},
"position": { "lat": -23.00052, "lng": -43.35129 },
"access": [{ "lat": -23.0004, "lng": -43.35129 }],
"distance": 47,
"categories": [{ "id": "700-7600-0116", "name": "Área de serviço", "primary": true }, { "id": "700-7400-0000", "name": "Serviços ao consumidor" }],
"chains": [{ "id": "4017" }],
"references": [{ "supplier": { "id": "core" }, "id": "1119174661" }],
"contacts": [{ "phone": [{ "value": "+552124310715" }, { "value": "+552124390109" }, { "value": "+553433174792" }], "www": [{ "value": "http://www.br.com.br" }] }]
},
{
"title": "Petrobras",
"id": "here:pds:place:07675cjh-1e866c2d3bcf4ed5bafe72e0084a389e",
"resultType": "place",
"address": {
"label": "Petrobras, Avenida das Américas, Barra da Tijuca, Rio de Janeiro - RJ, 22790-703, Brasil",
"countryCode": "BRA",
"countryName": "Brasil",
"stateCode": "RJ",
"state": "Rio de Janeiro",
"city": "Rio de Janeiro",
"district": "Barra da Tijuca",
"street": "Avenida das Américas",
"postalCode": "22790-703"
},
"position": { "lat": -23.00026, "lng": -43.36029 },
"access": [{ "lat": -23.00026, "lng": -43.36029 }],
"distance": 889,
"categories": [{ "id": "700-7600-0116", "name": "Área de serviço", "primary": true }, { "id": "600-6000-0061", "name": "Loja de Conveniência" }],
"chains": [{ "id": "4017" }],
"references": [{ "supplier": { "id": "core" }, "id": "1202359863" }, { "supplier": { "id": "core" }, "id": "898136652" }, { "supplier": { "id": "core" }, "id": "898138299" }],
"contacts": [
{
"www": [
{ "value": "http://www.shell.com.br" },
{ "value": "https://find.shell.com/br/fuel/RBLA_BR_1024423-posto-shell-auto-posto-nova-ipanema-ltda" },
{ "value": "https://find.shell.com/br/fuel/RBLA_BR_171425-posto-shell-j-p-x-comb-e-conv-barra-ltda" }
]
}
]
}
]
}
Language preference
Applications needing to enforce a preferred language in the /browse
result items need to set the lang
parameter to the necessary BCP 47 language code. Where possible, the endpoint will present the slice-and-diced response items in the expected language. If lang
is not set, or if the result item has no translation in the requested language, the default language will be used.
Surroundings
A special use-case served by /browse
is to return surrounding places, streets or localities at a given position without any names or categories filtering.
For example, to get the 10 items at the position (41.89344,-87.62406)
in Chicago Millennium Mile, a customer would send:
GET https://browse.search.hereapi.com/v1/
browse
?at=41.89344,-87.62406
&limit=10
Bearer [your token]
The expected result for this query would be the following:
{
"items": [
{
"title": "BURBERRY",
"id": "here:pds:place:840dp3wq-bb300b5b4fe04484847007a0d56257c0",
"resultType": "place",
"address": {
"label": "BURBERRY, 633 N Michigan Ave, Chicago, IL 60611, United States",
"countryCode": "USA",
"countryName": "United States",
"stateCode": "IL",
"state": "Illinois",
"county": "Cook",
"city": "Chicago",
"district": "River North",
"street": "N Michigan Ave",
"postalCode": "60611",
"houseNumber": "633"
},
"position": { "lat": 41.8935, "lng": -87.62387 },
"access": [{ "lat": 41.8935, "lng": -87.6242 }],
"distance": 17,
"categories": [
{ "id": "600-6800-0089", "name": "Men's Apparel", "primary": true },
{ "id": "600-6800-0000", "name": "Clothing & Accessories" },
{ "id": "600-6800-0090", "name": "Women's Apparel" },
{ "id": "600-6800-0091", "name": "Children's Apparel" },
{ "id": "600-6800-0092", "name": "Shoes/Footwear" }
],
"chains": [{ "id": "8267" }],
"references": [{ "supplier": { "id": "core" }, "id": "1010449725" }, { "supplier": { "id": "yelp" }, "id": "R3aC67jIrdCl54d98W6jDA" }],
"contacts": [
{
"phone": [{ "value": "+13127872500" }],
"fax": [{ "value": "+13078362328" }],
"www": [
{ "value": "https://uk.burberry.com/store-locator/united-states/633-north-michigan-avenue-chicago/1573" },
{ "value": "https://us.burberry.com/stores/chicago/?utm_source=Yext&utm_medium=organic&utm_campaign=US1573" },
{ "value": "https://www.burberry.com/" }
],
"email": [{ "value": "customerservice@burberry.com" }]
}
],
"openingHours": [
{
"text": ["Mon-Sat: 10:00 - 20:00", "Sun: 12:00 - 18:00"],
"isOpen": false,
"structured": [
{ "start": "T100000", "duration": "PT10H00M", "recurrence": "FREQ:DAILY;BYDAY:MO,TU,WE,TH,FR,SA" },
{ "start": "T120000", "duration": "PT06H00M", "recurrence": "FREQ:DAILY;BYDAY:SU" }
]
}
]
},
{
"title": "Woman's Athletic Club",
"id": "here:pds:place:840dp3wq-ffceb707caa9431b8264c144f862de7b",
...
},
{
"title": "Michigan & Ontario",
"id": "here:pds:place:840dp3wq-60621060ea2849839c023fb68db4f3e6",
...
},
{
"title": "Orvis",
"id": "here:pds:place:840dp3wq-8959f7446df6489fb701ec2a4f9b9f6f",
...
},
{
"title": "National Certification for",
"id": "here:pds:place:840dp3wq-5e2d395c96594e62bdcde3f9d66a667b",
...
},
{
"title": "Foem",
"id": "here:pds:place:840dp3wq-3a67225e91714734a81a77892834ad06",
...
},
{
"title": "Tba",
"id": "here:pds:place:840dp3wq-2e9078a1977d45b4a835772f55627b54",
...
},
{
"title": "Dr Ronna Fisher, Aud",
"id": "here:pds:place:840dp3wq-21c68ec65ea805d7377a20e5806d0986",
...
},
{
"title": "American College of Osteopathic Emergency Physicians",
"id": "here:pds:place:8403fv6k-c274f77fa7c6092e6268eccaa23f3f70",
...
},
{
"title": "Children Law Group",
"id": "here:pds:place:8403fv6k-95f911c8bf8d0c52b2ef97ff8fca2a0f",
...
}
]
}
The first result is a luxury shop, the second a bus stop, etc.
To make sure that results only contain places, a whitelist of all level 1 categories is necessary:
GET https://browse.search.hereapi.com/v1/
browse
?at=41.89344,-87.62406
&limit=10
&categories=100,200,300,350,400,500,550,600,700,800,900
Bearer [your token]
Along the route
Last but not least, /browse
like /autosuggest
and /discover
supports search along the route through the addition of a route
parameter to the at
parameter. Check Implementing Search along the route for specifics.
Filtering versus One-box
Whereas /discover
anticipates the intention of the submitter's (human) search request, the /browse
endpoint takes a more machine-oriented or precise interpretation of the request.
For example, if you submit a request for for "New York Pizza", /discover
returns results for restaurants in New York City serving pizza. Whereas, /browse
returns a restaurant named "New York Pizza".
As another example, german end-users would formulate a search query for gas-stations with the phrase "Tankstellen" sent to the /discover
endpoint, while an in-car application would propose pre-defined category search shortcuts linked to the /browse
endpoint together with associated catgory ids like 700-7600-0000
for gas-stations.
The sorting is similarly contrasted: for /discover
endpoint results are mostly sorted by relevance, whereas in /browse
, results are always sorted by distance.