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

/browse allows you to retrieve places at a given position for a specific HERE Places category or HERE Places cuisine. For this, the query parameters categories and foodTypes are used respectively.

HERE Places categories can be specified as values for the categories field at any of their 3 levels:

level 1 for a high level (ex: 100 for places where you can eat and drink)
level 2 for intermediate granularity (ex: 100-1000 for restaurant places) or
level 3 for fine grained categories (ex: 100-1000-0002 for fine dining places),

HERE Places cuisines can be specified as values for the foodTypes field at any of their 2 levels:

level 1 for a high level (ex: 201 for places serving Chinese cuisine)
level 2 for fine grained cuisines (ex: 201-009 for places serving Chinese cuisine from Szechuan)

Both categories and foodTypes query fields support multiple values, provided they are separated by a comma.

Example 1

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=47.80049,3.57119
    &limit=2
    &categories=700-7600-0000,700-7600-0116

Authorization: Bearer [your token]

The expected result for this query would be the following:

{
  "items": [
    {
      "title": "Auxerdis",
      "id": "here:pds:place:250u06xc-62c7b2d0e6984a74ae5d87fb30118edb",
      "resultType": "place",
      "categories": [{ "id": "700-7600-0116", "name": "Station d'essence", "primary": true }],
      "chains": [{ "id": "253" }],
      ...
    },
    {
      "title": "E.Leclerc",
      "id": "here:pds:place:250u06xc-ca70f6124edf476a84aee07fbd2a0a08",
      "resultType": "place",
      "categories": [
        { "id": "600-6300-0066", "name": "Supermarché", "primary": true },
        { "id": "600-6200-0063", "name": "Magasin à rayons" },
        { "id": "600-6400-0070", "name": "Pharmacien" },
        { "id": "600-6500-0072", "name": "Magasin de produits électroniques" },
        { "id": "600-6500-0075", "name": "Matériel et logiciels informatiques" },
        { "id": "600-6700-0087", "name": "Librairie" },
        { "id": "600-6900-0000", "name": "Produits de consommation" },
        { "id": "600-6900-0102", "name": "Magasin de variétés" },
        { "id": "600-6900-0103", "name": "Cadeaux, antiquités et art" },
        { "id": "700-7600-0116", "name": "Station d'essence" },
        { "id": "700-7851-0117", "name": "Agence de location de voitures" }
      ],
      "chains": [{ "id": "253" }],
      ...
    }
  ]
}

Example 2

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

Authorization: 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" }
      ],
      ...
    }
  ]
}

Example 3

The mobile phone application of previous example could use the combination of restaurant categories and the cuisine they serve:

fast food (100-1000-0009)
either Indian or Pakistani cuisine (202 or 208)

So that a query from a position in London would look like:

GET https://browse.search.hereapi.com/v1/
    browse
    ?at=51.51979,-0.088
    &limit=5
    &categories=100-1000-0009
    &foodTypes=202,208

Authorization: Bearer [your token]

The expected result for this query would be:

{
  "items": [
    {
      "title": "Spices",
      "id": "here:pds:place:826jx7ps-328d2363d60902e717316b1e5db13559",
      "resultType": "place",
      "categories": [
        { "id": "100-1000-0000", "name": "Restaurant", "primary": true },
        { "id": "100-1000-0009", "name": "Fast Food" }
      ],
      "foodTypes": [{ "id": "202-000", "name": "Indian", "primary": true }],
      ...
    },
    {
      "title": "Barbican Express",
      "id": "here:pds:place:826gcpvj-d20d7e1bc2dc44a786aed76a2db8388a",
      "resultType": "place",
      "categories": [
        { "id": "100-1000-0000", "name": "Restaurant", "primary": true },
        { "id": "100-1000-0003", "name": "Take Out & Delivery Only" },
        { "id": "100-1000-0004", "name": "Food Market/Stall" },
        { "id": "100-1000-0009", "name": "Fast Food" },
        { "id": "100-1100-0000", "name": "Coffee/Tea" }
      ],
      "foodTypes": [
        { "id": "304-000", "name": "Italian", "primary": true },
        { "id": "202-000", "name": "Indian" },
        { "id": "800-057", "name": "Pizza" }
      ],
      ...
    },
    ...
  ]
}

Place chain filter

Additionally to categories and foodTypes query filters, /browse endpoint also propose a chains query filter. Any combination of HERE chain id can be used to retrieve places of the related chains.

For instance, a car manufacturer's companion app can use the filters categories=700-7850-0122&chains=299 to only retrieve nearby repairs for the car manufacturer's brand.

Negative filtering

/browse also allows you to retrieve places that do not have specific categories, cuisines or chains. For this an exclamation mark ("!") is necessary in front of the category ID , the cuisine ID or the chain ID. Negated and regular values can be mixed into the same field. 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=47.80049,3.57119
    &limit=2
    &categories=700-7600-0000,700-7600-0116

Authorization: Bearer [your token]

The expected result for this query would be the following:

{
  "items": [
    {
      "title": "Auxerdis",
      "id": "here:pds:place:250u06xc-62c7b2d0e6984a74ae5d87fb30118edb",
      "resultType": "place",
      "categories": [{ "id": "700-7600-0116", "name": "Station d'essence", "primary": true }],
      "chains": [{ "id": "253" }],
      ...
    },
    {
      "title": "E.Leclerc",
      "id": "here:pds:place:250u06xc-ca70f6124edf476a84aee07fbd2a0a08",
      "resultType": "place",
      "categories": [
        { "id": "600-6300-0066", "name": "Supermarché", "primary": true },
        { "id": "600-6200-0063", "name": "Magasin à rayons" },
        { "id": "600-6400-0070", "name": "Pharmacien" },
        { "id": "600-6500-0072", "name": "Magasin de produits électroniques" },
        { "id": "600-6500-0075", "name": "Matériel et logiciels informatiques" },
        { "id": "600-6700-0087", "name": "Librairie" },
        { "id": "600-6900-0000", "name": "Produits de consommation" },
        { "id": "600-6900-0102", "name": "Magasin de variétés" },
        { "id": "600-6900-0103", "name": "Cadeaux, antiquités et art" },
        { "id": "700-7600-0116", "name": "Station d'essence" },
        { "id": "700-7851-0117", "name": "Agence de location de voitures" }
      ],
      "chains": [{ "id": "253" }],
      ...
    }
  ]
}

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

Authorization: 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=51.51979,-0.088
    &limit=5
    &categories=100-1000-0009
    &foodTypes=202,208

Authorization: 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.

Browse

Browse

Location context and geographic filter

Multigranular place category filter

Example 1

Example 2

Example 3

Place chain filter

Negative filtering

Name filter

Language preference

Surroundings

Along the route

Filtering versus One-box

results matching ""

No results matching ""

Developer