Ratings API

Get location ratings for any address (or latitude & longitude) around the world to your apps.

Jump to:

get started

The Ratings API lets you search for location ratings based on an address or a set of latitude and longitude coordinate.

The Ratings are calculated based on the adjacent amenities

A Ratings API request is an HTTP URL of the following form:

https://api.urbern.com/v1/ratings?parameters
parameters
input

[Optional] You can switch between address and latitude & longitude by specifying address or latlng in the input parameters.

if the input parameter is omitted, the API server expects an address parameter.

input=address
input=latlng
address

if the input parameter is set to be address or is omitted, the API server expects an address parameter.

Please specify addresses in accordance with the format used by the national postal service of the country concerned. Additional address elements such as business names and unit, suite or floor numbers should be avoided. Street address elements should be delimited by spaces (shown here as url-escaped to %20):

address=483%20George%20St%20Sydney%20NSW%202000

The above example sets 483 George St Sydney NSW 2000 as the address parameter.

latlng

if the input parameter is set to be latlng, the API server expects one lat and one lng parameters.

Please ensure that the latitude coordinate is between -90 and 90, and the longitude coordinate is between -180 and 180.

The latitude and longitude coordinates should be formatted in decimal degrees

input=latlng&lat=-33.7875762&lng=151.1767907

The above example sets -33.7875762 as lat and 151.1767907 as lng parameters.

key

This is your own API key in order for the request to work in your application.

key=uM6EYLuQcmB5jMN6pBggnx5qHV6KG5ORKl5T2J4s1ZQ

The above key example is for demonstration only, it is not a valid key. Please contact eddy@urbern.com to request an API key.

examples
https://api.urbern.com/v1/ratings?address=483%20George%20St%20Sydney%20NSW%202000&key=uM6EYLuQcmB5jMN6pBggnx5qHV6KG5ORKl5T2J4s1ZQ

In the above example, the input parameter is omitted, so the API server expects an address parameter and a key parameter.

https://api.urbern.com/v1/ratings?input=address&address=483%20George%20St%20Sydney%20NSW%202000&key=uM6EYLuQcmB5jMN6pBggnx5qHV6KG5ORKl5T2J4s1ZQ

In the above example, the input parameter is explicitly set to address. It returns the same response as the first example.

http://api.urbern.com/v1/ratings?input=latlng&lat=-33.873183&lng= 151.2061462&key=uM6EYLuQcmB5jMN6pBggnx5qHV6KG5ORKl5T2J4s1ZQ

In the above example, the input parameter is explicitly set to latlng. the API server expects lat & lng parameters as the input parameters. It returns the same result as the first example, because the latitude and longitude coordinates are pinpointed at 483 George St Sydney NSW 2000.

The latlng is built for batch geospatial analysis, when a list of latitude and longitude coordinates are known to the developer.

RESULTS

The above examples return the results in the following JSON format.

Please note that the response may take up to 12 seconds to load.

{
  "urbern_rating": 9.94,
  "categories": [
    {
      "name": "Shopping",
      "rating": 10.0,
      "amenities_total": 236,
      "user_ratings_total": 128634
    },
    {
      "name": "Dining",
      "rating": 10.0,
      "amenities_total": 205,
      "user_ratings_total": 144505
    },
    {
      "name": "Transit",
      "rating": 9.83,
      "amenities_total": 76,
      "user_ratings_total": 1879
    }
  ],
  "latitude": -33.873183,
  "longitude": 151.2061462,
  "request_id": "ae738c2370afb68b7750f0945dae6c36",
  "status": "Successful",
  "timestamp": "2022-08-11T08:31:12.857586Z",
  "validity_period": "28 days",
  "expiration_time": "2022-09-08T08:31:12.857586Z"
}

urbern_rating is the overall URBERN rating at the address, it’s a decimal ranging between 0 to 10.

categories is a list of categories. In each category, it contains the category name, the category rating, a total number of adjacent amenities under the category (amenities_total), and a total number of user ratings under the category(user_ratings_total, i.e. the sum of the numbers of users who have rated the premises under the category).

Additional categories will be added to the categories list when available.

latitude & longitude is the coordinate at the location. They should be respectively the same as the lat & lng parameters if the parameters are provided in the HTTP Request

request_id is the id of this particular request, this is for troubleshooting and billing purposes.

status is the status of the HTTP Response. The outcomes are either “Successful” or “Failed”, if the status is “Failed”, it should advise with the reason.

timestamp records the time of the request.

validity_period is the duration the Ratings are valid for. It usually lasts for 28 days. Our empirical study finds that Ratings at locations change over the time, as new businesses open and old ones close.

expiration_time is the time when the Ratings expire. Once expired, it is recommended to call the API again and obtain the most up-to-date Ratings at the address.

Close Bitnami banner
Bitnami