Nearby

Get nearest points of interest based on a specified location.

  1. Overview
  2. Required Parameters
  3. Optional parameters
  4. Response
  5. 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 interest that should be returned as suggestions.

List of covered point of interest:

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.

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