Nearby

Get nearest points of interest based on a specified location.

  1. Overview
  2. Required Parameters
  3. Optional parameters
  4. Response
  5. Samples
  6. Usage limits

Overview

Woosmap Localities Nearby allows you to look for points of interest within a defined area (latitude, longitude and a radius). You can narrow down your query by specifying the category you are seeking.

A Woosmap Localities nearby request is an HTTP URL of the following form:

http
        https://api.woosmap.com/localities/nearby?key={PUBLIC_API_KEY}&location={COORDINATES}&types{LIST_OF_TYPES}

    

Required Parameters

location

The point around which to retrieve place information. It must be specified in the latitude,longitude string format.

types

The types of suggestion to return. Currently, only point_of_interest is supported by Localities Nearby. More types will be included in future updates.

key

Your project’s API key. This key identifies your Woosmap Project for security and quota management purposes. Public keys are designed to be used client side, where every request contain a referer. Alternatively, you can use the parameter private_key for server side requests.

Reminder: To use the Localities API, your Public API key (parameter key) has to be authorized for the domains and/or IPs (referer) where you make the call. More on securing API keys here.

You must use the key parameter OR the private_key parameter. Sending both keys will result in an error.

private_key

Your project’s private API key. This key identifies your Woosmap Project for purposes of security and quota management. Private keys are designed to be used server side, no referer checking associated with those keys.

You must use the key parameter OR the private_key parameter. Sending both keys will result in an error.

Optional parameters

radius

This parameter may be used in addition to the location parameter to define the distance in meters within which the API will return results. When not specified, radius defaults to 1000 meters

categories

This allows you to specify the categories of points of interests that should be returned as suggestions. Multiple categories can be passed using the pipe character (|) as a separator. For example: categories=business.shop|medical.pharmacy|bank. The complete list of categories can be found here

excluded_categories

This allows you to specify categories you want to exclude from the results. Multiple categories can be passed using the pipe character (|) as a separator. For example: excluded_categories=business.food_and_drinks.fast_food|business.food_and_drinks.pub The list of categories to exclude can be found here

List of categories for point of interest:

The following are the commonly used categories. A detailed list is available here:

business All commercial establishments, such as malls, restaurants, and retail shops.
education All establishments related to education like school or university
government Government buildings
hospitality A place or business that provides accommodations, services, and amenities to guests
medical All establishments related to medical like hospital, clinic or pharmacy
park All recreational areas such as public parks, nature reserves, or gardens.
place_of_worship Places of worship, including churches, temples, mosques, and others
police Law enforcement locations, such as police stations.
post_office Post office
sports Sports complex like football fields or tennis court.
tourism All establishments related to tourism
transit.station Transit stations e.g. airport, rail

limit

Defines how many results should be included in single page. In case of navigation between pages, limit must not be updated. When not specified, limit defaults to 10 points of interest.

page

Use page to navigate through paginated results. In the response, pagination object informs about a potential next page.

Response

Localities Nearby provides a JSON response containing 2 root elements, pagination, that helps to navigate through paginated results, and results, which contains an array of suggestions sorted from nearest to farthest.

Localities Nearby Collection Response
JSON
        {
  "results":
    [
      {
        "public_id": "emXdi2D7RXOpIthsEyKVGBYZVSc=",
        "types": ["point_of_interest"],
        "categories": ["business.finance.bank"],
        "name": "Citibank",
        "geometry":
          { "location": { "lat": 40.7130414767567, "lng": -74.0074818610995 } },
        "address_components":
          [
            {
              "types": ["country", "administrative_area_level_0"],
              "long_name": "United States",
              "short_name": "us",
            },
          ],
      },
      {
        "public_id": "95FQZAdnETzbfFTEFVb/oofxJ4U=",
        "types": ["point_of_interest"],
        "categories": ["business.food_and_drinks.restaurant"],
        "name": "Gran Morsi",
        "geometry":
          {
            "location": { "lat": 40.71432885326513, "lng": -74.00778746528921 },
          },
        "address_components":
          [
            {
              "types": ["country", "administrative_area_level_0"],
              "long_name": "United States",
              "short_name": "us",
            },
          ],
      },
      {
        "public_id": "c5rIR48wx55zG9RmeFYI7yujDwg=",
        "types": ["point_of_interest"],
        "categories": ["business.food_and_drinks.restaurant"],
        "name": "Saffron",
        "geometry":
          {
            "location": { "lat": 40.714654825479556, "lng": -74.0077106032371 },
          },
        "address_components":
          [
            {
              "types": ["country", "administrative_area_level_0"],
              "long_name": "United States",
              "short_name": "us",
            },
          ],
      },
      {
        "public_id": "eFFoZUgHxyJJNH+Hpm2MbBXPg5Y=",
        "types": ["point_of_interest"],
        "categories": ["business.food_and_drinks.fast_food"],
        "name": "Burger King",
        "geometry":
          {
            "location": { "lat": 40.71619516782573, "lng": -74.00480635760651 },
          },
        "address_components":
          [
            {
              "types": ["country", "administrative_area_level_0"],
              "long_name": "United States",
              "short_name": "us",
            },
          ],
      },
      {
        "public_id": "6GSB3ngwjf3vpdOUnj2TZO2ecOc=",
        "types": ["point_of_interest"],
        "categories": ["business.food_and_drinks.fast_food"],
        "name": "Dunkin'",
        "geometry":
          {
            "location": { "lat": 40.71471299588757, "lng": -74.00777455715831 },
          },
        "address_components":
          [
            {
              "types": ["country", "administrative_area_level_0"],
              "long_name": "United States",
              "short_name": "us",
            },
          ],
      },
      {
        "public_id": "GjVqQF0y4/8+puILSl4GwcvTpG8=",
        "types": ["point_of_interest"],
        "categories": ["business.shop.grocery"],
        "name": "Barakth & Saiful",
        "geometry":
          {
            "location": { "lat": 40.71499001778744, "lng": -74.00766701734061 },
          },
        "address_components":
          [
            {
              "types": ["country", "administrative_area_level_0"],
              "long_name": "United States",
              "short_name": "us",
            },
          ],
      },
      {
        "public_id": "FAs4bm8/XWAzeqIfWy3c5vNNuJM=",
        "types": ["point_of_interest"],
        "categories": ["business.food_and_drinks.cafe"],
        "name": "Hungry Ghost",
        "geometry":
          {
            "location": { "lat": 40.71527793616147, "lng": -74.00745294353355 },
          },
        "address_components":
          [
            {
              "types": ["country", "administrative_area_level_0"],
              "long_name": "United States",
              "short_name": "us",
            },
          ],
      },
      {
        "public_id": "eev6v7sxhhbvAagkbC5NAKqzGV8=",
        "types": ["point_of_interest"],
        "categories": ["business.shop.grocery"],
        "name": "Mr. Exotix",
        "geometry":
          {
            "location": { "lat": 40.71523761920719, "lng": -74.00749141646912 },
          },
        "address_components":
          [
            {
              "types": ["country", "administrative_area_level_0"],
              "long_name": "United States",
              "short_name": "us",
            },
          ],
      },
      {
        "public_id": "VDUWUBQS+dBD6NJyMqfEondAEZE=",
        "types": ["point_of_interest"],
        "categories": ["business.shop.grocery"],
        "name": "Civic Deli",
        "geometry":
          {
            "location": { "lat": 40.71606784671653, "lng": -74.00377261748812 },
          },
        "address_components":
          [
            {
              "types": ["country", "administrative_area_level_0"],
              "long_name": "United States",
              "short_name": "us",
            },
          ],
      },
      {
        "public_id": "X8aAA+6/fLGaHeZkbc6EiqzOVR8=",
        "types": ["point_of_interest"],
        "categories": ["business.shop.grocery"],
        "name": "Tribeca Deli Grill",
        "geometry":
          {
            "location": { "lat": 40.7149423247584, "lng": -74.00771462655064 },
          },
        "address_components":
          [
            {
              "types": ["country", "administrative_area_level_0"],
              "long_name": "United States",
              "short_name": "us",
            },
          ],
      },
    ],
  "pagination": { "previous_page": 2, "next_page": 4 },
}

    

Suggestion results can contain the following fields:

public_id

Contains a unique ID for each suggestion.

types

Contains the types of the suggestion, See the list of existing types.

categories

Contains the categories of the suggestion, See the list of existing categories.

geometry

The location of the result, in latitude and longitude.

address_components

Detailed fields of the result (long and short). Currently, only country code is returned by Localities Nearby. More components will be included in future updates.

Samples

Usage limits

The following usage limits are in place for the Localities API on the nearby endpoint:

Was this article helpful?
Have more questions? Submit a request