Skip to main content

Points of Interest

Stable
US 🇺🇸 and Canada 🇨🇦

Description​

Points of interest (POIs) near a location can be accessed via Local Logic’s POIs endpoint, documented below. Our POIs represent businesses, services, public transit stops, parks, and any locations which generally impact the lifestyle fit and accessibility of an area.

info

The Enhanced POIs endpoint is now available to all users with access to v3/pois!

This endpoint is a new Local Logic endpoint offering new functionality for querying and accessing points of interest, including filtering by brands and tags. It contains the same points of interest as the v3/pois endpoint and its use is optional. Try it out today!

GET v3/enhanced-pois​

Points of interest near a location can be accessed via Local Logic’s enhanced POIs endpoint, documented below. The POIs available to this endpoint are the same underlying ones as those available via the v3/pois endpoint above. However, an Enhanced Point of Interest (enhanced POI) will also include one or more categories, zero or more brands and zero or more tags. The enhanced POIs endpoint can be filtered by any, all or none of categories, brands and tags. The category list differs slightly between the two POI endpoints. Brands can be used to search for or identify specific types of businesses based on the brand names. For example: Starbucks, Whole Foods, or Canadian Tire. Tags are used to further distinguish restaurant types (healthy, "unhealthy," and type of cuisine), and is also used to tag independent businesses or chain stores. Enhanced POIs will be returned in order of least to greatest linear_distance away from the specified lat/lng (or the center of the specified polygon).

GET v3/enhanced-pois

POI Categories​

The following categories of enhanced POIs are available. This list is also accessible from the v3/enhanced-pois/categories endpoint documented below.

CategoryPOI Category Idenftifier
Alcohol Shopsalcohol
Airportsairports
Art, Culture and Scienceart_culture_science
Bus Stopsbus_stops
Cafescafes
Car Fueling Stationscar_fueling_stations
Clothing Shopsclothing
Common Needs Shopscommon_needs
Conference Centersconference_centers
Daycaresdaycares
Entertainmententertainment
Fitnessfitness
Groceries (General)groceries
Groceries (Specialized)groceries_specialized
Health Carehealth_care
Home Improvementhome_improvement
Hospitalshospitals
Librarieslibraries
Nightlifenightlife
Parksparks
Personal Carepersonal_care
Pet Carepet_care
Pharmaciespharmacies
Rapid Transit Stationsrapid_transit_stations
Restaurantsrestaurants
Retailretail
Shops and Servicesshops_and_services
Sport Facilitiessport_facilities
Train Stationstrain_stations

An enhanced POI may have more than one category; but will not appear more than once in the response.

Enhanced POIs may also be filtered by brands and tags. The full list of available brands and tags is very long and will increase over time as more data is included. To find out what brands and tags are available, the v3/enhanced-pois/brands and v3/enhanced-pois/tags endpoints can be queried.

This API uses JWT token based authentication. This JWT Bearer token is what is used to populate the Authorization header below.

Instructions on how to retrieve this token can be found at Getting Started.

HeaderStatusDescription
AuthorizationrequiredYour bearer token retrieved from our authorization API, ex. Bearer eyJhbGci...
AcceptrequiredThe datatype to request, this API will return application/json.

QueryString​

The region to be queried by the endpoint can be defined two ways: (1) by specifying a lat/lng coordinate, with optional radius parameters, (2) or by providing a polygon parameter.

When using the lat/lng coordinate query method without specifying radius parameter, the endpoint will return points of interest within 5km of the coordinates. When including radius parameters, the resulting circular area around the lat/lng coordinate will be queried.

When using the polygon query method, the points of interest returned will be contained in the region defined by the polygon area. Polygons are specified using the WKT format. The only accepted type is POLYGON, and holes are not supported. Each polygon point must be defined as a lng/lat coordinate.

API Limitations

  1. The polygon query string has been limited to 5000 chars.
  2. The polygon must fit inside a bounding box with a diagonal distance of less than 70km between its southwest and northeast corners.
  3. The radius is limited to 25km.

Up to 500 POIs will be returned.

proximity.linear_distance data is provided in the response in meters.

warning

WKT works on x/y planes. Therefore, the coordinates must be sent as lng/lat instead of lat/lng.

ParameterStatusDescription
latoptionalA decimal number between -90 and 90 (Latitude)
lngoptionalA decimal number between -180 and 180 (Longitude)
radiusoptionalA positive float number (Circle radius)
polygonoptionalList of 2D lng/lat points that define a 2D polygon, using the WKT representation
categoriesoptionalA comma separated list of enhanced POI category identifiers. See the above table's POI Category Idenftifier column for a full list of available categories, or see v3/enhanced-pois/categories. The default will include all of them.
brandsoptionalA comma separated list of brand idenftifiers. See v3/enhanced-pois/brands for a full list of available brands. The default will include all of them.
tagsoptionalA comma separated list of tag identifiers. See v3/enhanced-pois/tags for a full list of available brands. The default will include all of them.
limitoptionalThe limit of enhanced POIs returned.

default: 500

maximum: 500
warning

Either polygon or both lat and lng must be populated, but not both.

If categories is populated, an enhanced POI will be returned if it is in any of the categories.

Usage examples​

  require('node-fetch')('https://api.locallogic.co/v3/enhanced-pois?' + new URLSearchParams({
lat: 41.855306,
lng: -87.668732,
categories: 'cafes,car_fueling_stations',
radius: 3000,
limit: 10
}), {
method: 'GET',
headers: {
Accept: 'application/json',
Authorization: 'Bearer eyJhbGciOiJ...'
}
})
.then(response => response.json())
.then(body => {
console.log(body)
})
.catch(error => {
console.log(error)
})

Response example​

{
"data": {
"results": [
{
"name": "Electric Charging Station",
"address": "1924 N Paulina St",
"city": "Chicago",
"state": "Illinois",
"country": "USA",
"postal_code": "60622-1127",
"lat": 41.855286,
"lng": -87.668752,
"proximity": {
"linear_distance": 2
},
"categories": [
"car_fueling_stations",
"retail",
"shops_and_services"
],
"brands": [],
"tags": [
"independent"
]
},
{
"name": "Brew Brew Coffee & Tea",
"address": "1641 W 18th St",
"city": "Chicago",
"state": "Illinois",
"country": "USA",
"postal_code": "60608-5356",
"phone": "(312) 796-3151",
"url": "http://brewbrewcoffeeandtea.com"
"lat": 41.857638,
"lng": -87.66784,
"proximity": {
"linear_distance": 269
},
"categories": [
"cafes",
"nightlife",
"shops_and_services"
],
"brands": [],
"tags": [
"independent",
"unhealthy"
],
},
{
"name": "Dunkin'",
"address": "1659 W 18th St",
"city": "Chicago",
"state": "Illinois",
"country": "USA",
"postal_code": "60608-2835",
"phone": "(312) 846-6141",
"url": "https://www.dunkindonuts.com"
"lat": 41.857674,
"lng": -87.667786,
"proximity": {
"linear_distance": 274
},
"categories": [
"cafes",
"shops_and_services"
],
"brands": [
"dunkin"
],
"tags": [
"chain",
"unhealthy"
],
},
// Plus other cafes and car_fueling_stations
]
},
"meta": {
"message": "Successfully called v3/enhanced-pois API.",
"type": "LocalLogic.API.Success",
"statusCode": 200,
"counts": {
"returned_by_category": {
"cafes": 6,
"car_fueling_stations": 4
},
"returned_count": 10,
"total_by_category": {
"cafes": 41,
"car_fueling_stations": 35
},
"total_count": 76
}
}
}

As seen in the example, not all enhanced POIs will include all possible fields. name, country, lat, lng, categories, brands and tags will always be included. total_by_category and total_count will always include the total number of pois matching the search criteria.

If an enhanced POI is in multiple requested categories, the sum of the values under returned_by_category and total_by_category will exceed returned_count and total_count.

GET v3/enhanced-pois/categories​

This endpoint will return a list of all available categories. It takes no query parameters and requires the same authorization as v3/enhanced-pois.

GET v3/enhanced-pois/categories

Usage examples​

  import requests

response = requests.get(
"https://api.locallogic.co/v3/enhanced-pois/categories",
headers={
"Accept": "application/json",
"Authorization": "Bearer eyJhbGciOiJ..."},
params={}
)

print(response.json())

Response example​

{
"data": {
"categories": [
"alcohol",
"groceries_specialized",
"cafes",
"car_fueling_stations",
// plus other categories
]
},
"meta": {
"message": "Successfully called v3/enhanced-pois/categories API.",
"type": "LocalLogic.API.Success",
"statusCode": 200
}
}

GET v3/enhanced-pois/brands​

This endpoint will return a list of all available brands. There are over 2000 of them. It takes no query parameters and requires the same authorization as v3/enhanced-pois.

GET v3/enhanced-pois/brands

Usage examples​

  import requests

response = requests.get(
"https://api.locallogic.co/v3/enhanced-pois/brands",
headers={
"Accept": "application/json",
"Authorization": "Bearer eyJhbGciOiJ..."},
params={}
)

print(response.json())

Response example​

{
"data": {
"brands": [
"16_handles",
"18_8_fine_mens_salons",
"1_800_dryclean",
// jumping ahead...
"staples",
"starbucks",
"starlight_cinemas",
"steak_n_shake",
// plus other brands
]
},
"meta": {
"message": "Successfully called v3/enhanced-pois/brands API.",
"type": "LocalLogic.API.Success",
"statusCode": 200
}
}

GET v3/enhanced-pois/tags​

This endpoint will return a list of all available tags. It takes no query parameters and requires the same authorization as v3/enhanced-pois.

GET v3/enhanced-pois/tags

Usage examples​

import requests

response = requests.get(
"https://api.locallogic.co/v3/enhanced-pois/tags",
headers={
"Accept": "application/json",
"Authorization": "Bearer eyJhbGciOiJ..."},
params={}
)

print(response.json())

Response example​

{
"data": {
"tags": [
"american",
"asian",
"asian_fusion",
"bakery",
"bbq",
"breakfast_brunch",
"chain",
"independent"
// plus other tags
]
},
"meta": {
"message": "Successfully called v3/enhanced-pois/tags API.",
"type": "LocalLogic.API.Success",
"statusCode": 200
}
}

GET v3/pois​

POIs will be returned in order of least to greatest linear_distance away from the specified lat/lng (or the center of the specified polygon) for each respective POI category.

GET v3/pois

POI Categories​

The following categories of POIs are available.

CategoryPOI Category Name
Art, Culture and Scienceart_culture_science
Airportsairports
Bus Stopsbus_stops
Cafescafes
Car Fueling Stationscar_fueling_stations
Daycaresdaycares
Fitnessfitness
Groceries (General)groceries
Groceries (Specialized)groceries_specialized
Health Carehealth_care
Healthy Restaurantshealthy_restaurants
Home Improvementhome_improvement
Nightlifenightlife
Parksparks
Personal Carepersonal_care
Pet Carepet_care
Rapid Transit Stationsrapid_transit_stations
Restaurantsrestaurants
Shoppingshopping
Sport Facilitiessport_facilities
Train Stationstrain_stations

Header​

This API uses JWT token based authentication. This JWT Bearer token is what is used to populate the Authorization header below.

Instructions on how to retrieve this token can be found at Getting Started.

HeaderStatusDescription
AuthorizationrequiredYour bearer token retrieved from our authorization API, ex. Bearer eyJhbGci...
AcceptrequiredThe datatype to request, this API will return application/json.

QueryString​

The region to be queried by the endpoint can be defined two ways: (1) by specifying a lat/lng coordinate, with optional radius parameters, (2) or by providing a polygon parameter.

When using the lat/lng coordinate query method without specifying radius parameter, the endpoint will return points of interest within 5km of the coordinates. When including radius parameters, the resulting circular area around the lat/lng coordinate will be queried.

When using the polygon query method, the points of interest returned will be contained in the region defined by the polygon area. Polygons are specified using the WKT format. The only accepted type is POLYGON, and holes are not supported. Each polygon point must be defined as a lng/lat coordinate.

API Limitations

  1. The polygon query string has been limited to 5000 chars.
  2. The polygon must fit inside a bounding box with a diagonal distance of less than 70km between its southwest and northeast corners.
  3. The radius is limited to 25km.

Up to 30 POIs can be obtained per category when multiple categories are called through the API. When a single category of POIs is requested in the parameters, up to 500 POIs will be returned.

proximity.linear_distance data is provided in the response in meters.

warning

WKT works on x/y planes. Therefore, the coordinates must be sent as lng/lat instead of lat/lng.

ParameterStatusDescription
latoptionalA decimal number between -90 and 90 (Latitude)
lngoptionalA decimal number between -180 and 180 (Longitude)
radiusoptionalA positive float number (Circle radius)
polygonoptionalList of 2D lng/lat points that define a 2D polygon, using the WKT representation
includerequiredA comma separated list of POI category names. See the above table's POI Category Name column for a full list of available categories.
limitoptionalThe limit of POIs returned per POI category.

default: 30

maximum: 30 if multiple POI categories specified in the include parameter, otherwise 500 if only one single POI category

Usage examples​

require('node-fetch')('https://api.locallogic.co/v3/pois?' + new URLSearchParams({
lat: 41.847206,
lng: -87.668825,
include: 'cafes,bus_stops',
radius: 3000,
limit: 10
}), {
method: 'GET',
headers: {
Accept: 'application/json',
Authorization: 'Bearer eyJhbGciOiJ...'
}
})
.then(response => response.json())
.then(body => {
console.log(body)
})
.catch(error => {
console.log(error)
})

Response example​

{
"data": {
"cafes": [
{
"name": "Tim Hortons",
"address": "11940 111 Ave Nw",
"city": "Edmonton",
"province": "AB",
"postalcode": "T5G0E5",
"country": "Canada",
"lat": 53.559654,
"lng": -113.528046,
"url": "http://timhortons.com/ca",
"proximity": {
"linear_distance": 0.491,
"walking": {
"quality": "calculated",
"distance": 0.522,
"travel_time": 6
}
}
},
{
"name": "European Sweetness Ltd",
"address": "12212 107 Ave Nw",
"city": "Edmonton",
"province": "AB",
"postalcode": "T5M4A8",
"country": "Canada",
"lat": 53.551163,
"lng": -113.53287,
"proximity": {
"linear_distance": 0.613,
"walking": {
"quality": "calculated",
"distance": 1.001,
"travel_time": 12
}
}
},
{
"name": "Second Cup",
"address": "11640 104 Ave Nw",
"city": "Edmonton",
"province": "AB",
"postalcode": "T5K2T7",
"country": "Canada",
"lat": 53.547203,
"lng": -113.52228,
"url": "http://secondcup.com",
"proximity": {
"linear_distance": 0.95,
"walking": {
"quality": "calculated",
"distance": 1.029,
"travel_time": 12
}
}
},
// Plus other cafes
],
"bus_stops": [
{
"name": "119 Street & 111 Avenue",
"country": "Canada",
"lat": 53.558764,
"lng": -113.526336,
"routes": [
{
"short_name": "125",
"long_name": "Belvedere - Jasper Place",
"route_color": "#FFFFFF",
"text_color": "#000000"
}
],
"proximity": {
"linear_distance": 0.386
}
},
// Plus other bus_stops
]
},
"meta": {
"message": "Successfully called v3/pois API.",
"type": "LocalLogic.API.Success",
"statusCode": 200,
"counts": {
"cafes": 10,
"bus_stops": 10
}
}
}

SDK Implementations​

POIs is used by two Local Logic SDKs:

SDKDescription
Local Content SDKRetrieves the POIs near a given location.
NeighborhoodMap SDKRetrieves the POIs within and close to the neighborhood.

Error codes​

When calling Local Logic’s API, you may receive an HTTP error code. These errors are explained below. In general, error codes starting with “4” are due to an invalid API call and can be fixed on your end, whereas error codes starting with “5” are due to server errors (that is, problems on our end). If you receive something not described here, please contact us at support@locallogic.co.

400 - BadRequest

This error code happens when the request inputs are incorrect. Use the detail field of the response for clarification. Example:

{
"code": "LocalLogic.API.BadRequest",
"detail": "ValidationErrors: AroundEndpoint is invalid:\n\tinclude is invalid: \"bad_input\" is not an acceptable value: \"groceries\", \"restaurants\", \"nightlife\", \"cafes\", \"shopping\", \"daycares\", \"primary_schools\", \"high_schools\""
}

401 - Unauthorized

This error code happens when your API key cannot access specific resources or locations. For example, some API keys can only access certain countries / states / provinces. Feel free to contact us for more information. Example:

{
"code": "LocalLogic.API.Unauthorized",
"detail": "Your API KEY doesn't support this region"
}

403 - Forbidden

This error code happens when you forgot to include security credentials with your request or you are requesting a parameter that you do not have access to. Example:

{
"message": "Forbidden"
}

404 - NotFound

This error code happens when we don’t have data for the requested location. For example, if you send a lat/lng pair for a location in Antarctica, we will return this error as we don’t have data for Antarctica (yet!). Example:

{
"code": "LocalLogic.API.NotFound",
"detail": "No Location Scores found for this location."
}

422 - Unprocessable Entity

This error code is returned when the correct parameters have been sent however, the data they contain is not valid. For example, if you send a lat/lng pair and the latitude is invalid (ie. not in the range [-90, 90]) and/or the longitude is invalid (ie. not in the range [-180, 180]).

{
"message": "Latitude must be within [-90, 90], Longitude must be within [-180, 180], Requires at least lat/lng pair, or geography_ids. None supplied.",
"code": "LocalLogic.API.BadRequest",
"statusCode": 422
}

500 - ServerError

This error code means that an error occurred on our end. Feel free to retry the same request to see if the problem persists. If you received a lot of these errors, please contact us at support@locallogic.co Example:

{
"code": "LocalLogic.API.ServerError",
"detail": "No Location Scores found for this location."
}

502 - BadGateway

This error code means that an error came from our cloud provider. Feel free to retry the same request to see if the problem persists. Example:

{
"message": "Internal server error"
}