Points of Interest

StableUS 🇺🇸 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.

Category	POI Category Idenftifier
Alcohol Shops	`alcohol`
Airports	`airports`
Art, Culture and Science	`art_culture_science`
Bus Stops	`bus_stops`
Cafes	`cafes`
Car Fueling Stations	`car_fueling_stations`
Clothing Shops	`clothing`
Common Needs Shops	`common_needs`
Conference Centers	`conference_centers`
Daycares	`daycares`
Entertainment	`entertainment`
Fitness	`fitness`
Groceries (General)	`groceries`
Groceries (Specialized)	`groceries_specialized`
Health Care	`health_care`
Home Improvement	`home_improvement`
Hospitals	`hospitals`
Libraries	`libraries`
Nightlife	`nightlife`
Parks	`parks`
Personal Care	`personal_care`
Pet Care	`pet_care`
Pharmacies	`pharmacies`
Rapid Transit Stations	`rapid_transit_stations`
Restaurants	`restaurants`
Retail	`retail`
Shops and Services	`shops_and_services`
Sport Facilities	`sport_facilities`
Train Stations	`train_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.

Header	Status	Description
Authorization	required	Your bearer token retrieved from our authorization API, ex. `Bearer eyJhbGci...`
Accept	required	The 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

The polygon query string has been limited to 5000 chars.
The polygon must fit inside a bounding box with a diagonal distance of less than 70km between its southwest and northeast corners.
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.

Parameter	Status	Description
lat	optional	A decimal number between `-90` and `90` (Latitude)
lng	optional	A decimal number between `-180` and `180` (Longitude)
radius	optional	A positive float number (Circle radius)
polygon	optional	List of 2D lng/lat points that define a 2D polygon, using the WKT representation
categories	optional	A 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.
brands	optional	A 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.
tags	optional	A 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.
limit	optional	The 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

NodeJS
Python

  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)
    })

import requests

response = requests.get(
  "https://api.locallogic.co/v3/enhanced-pois",
  headers={
    "Accept": "application/json",
    "Authorization": "Bearer eyJhbGciOiJ..."},
  params={
    "lat": 41.855306,
    "lng": -87.668732,
    "categories": 'cafes,car_fueling_stations',
    "radius": 3000,
    "limit": 10
  }
)

print(response.json())

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

Python

  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

Python

  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

Python

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.

Category	POI Category Name
Art, Culture and Science	`art_culture_science`
Airports	`airports`
Bus Stops	`bus_stops`
Cafes	`cafes`
Car Fueling Stations	`car_fueling_stations`
Daycares	`daycares`
Fitness	`fitness`
Groceries (General)	`groceries`
Groceries (Specialized)	`groceries_specialized`
Health Care	`health_care`
Healthy Restaurants	`healthy_restaurants`
Home Improvement	`home_improvement`
Nightlife	`nightlife`
Parks	`parks`
Personal Care	`personal_care`
Pet Care	`pet_care`
Rapid Transit Stations	`rapid_transit_stations`
Restaurants	`restaurants`
Shopping	`shopping`
Sport Facilities	`sport_facilities`
Train Stations	`train_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.

Header	Status	Description
Authorization	required	Your bearer token retrieved from our authorization API, ex. `Bearer eyJhbGci...`
Accept	required	The 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.

API Limitations

The polygon query string has been limited to 5000 chars.
The polygon must fit inside a bounding box with a diagonal distance of less than 70km between its southwest and northeast corners.
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.

Parameter	Status	Description
lat	optional	A decimal number between `-90` and `90` (Latitude)
lng	optional	A decimal number between `-180` and `180` (Longitude)
radius	optional	A positive float number (Circle radius)
polygon	optional	List of 2D lng/lat points that define a 2D polygon, using the WKT representation
include	required	A comma separated list of POI category names. See the above table's POI Category Name column for a full list of available categories.
limit	optional	The 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

NodeJS
Python

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)
})

import requests

response = requests.get(
  "https://api.locallogic.co/v3/pois",
  headers={
    "Accept": "application/json",
    "Authorization": "Bearer eyJhbGciOiJ..."},
  params={
    "lat": 43.593611,
    "lng": -79.536194,
    "include": 'cafes,bus_stops',
    "radius": 3000,
    "limit": 10
  }
)

print(response.json())

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:

SDK	Description
Local Content SDK	Retrieves the POIs near a given location.
NeighborhoodMap SDK	Retrieves 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"
}

Description​

GET v3/enhanced-pois​

POI Categories​

Header​

QueryString​

Usage examples​

Response example​

GET v3/enhanced-pois/categories​

Usage examples​

Response example​

GET v3/enhanced-pois/brands​

Usage examples​

Response example​

GET v3/enhanced-pois/tags​

Usage examples​

Response example​

GET v3/pois​

POI Categories​

Header​

QueryString​

Usage examples​

Response example​

SDK Implementations​

Error codes​

401 - Unauthorized

403 - Forbidden

404 - NotFound

422 - Unprocessable Entity

500 - ServerError

502 - BadGateway

Description

GET `v3/enhanced-pois`

POI Categories

Header

QueryString

Usage examples

Response example

GET `v3/enhanced-pois/categories`

Usage examples

Response example

GET `v3/enhanced-pois/brands`

Usage examples

Response example

GET `v3/enhanced-pois/tags`

Usage examples

Response example

GET `v3/pois`

POI Categories

Header

QueryString

Usage examples

Response example

SDK Implementations

Error codes