Search, Place Rank, and Existence

Alert: We are sun-setting access to the V3 APIs (Read, Schema, Facets, Submit). Learn more.

Introduction

When performing searches through Factual’s API, we provide a number of features to help you tune the way results are matched against your specific requirements. In particular:

Sorting Results

Once you’ve conducted a search through the API, you’ll receive a list of search results for your search. In most cases, there will be significantly more rows that match your your search parameters than can be returned with a single page of results. Sorting helps you specify which places should be near the top of your results to best satisfy your customers’ needs.

Standard Sorting

Standard sorting works like sorting a column in a spreadsheet- you choose the column you want to sort by, and the direction you want that column sorted (alphabetically/ordinally ascending or descending). Standard sorts also let you sort on a few “virtual” columns that may be available based on the type of data you are accessing, or the style of query you composed.

Examples:

sort=name:asc
sort=region:asc,name:asc
sort=$distance
sort=$relevance
sort=placerank:desc

In these examples, $distance is a virtual column that is only available if your query included a point/radius based geo query. $relevance is only available if you performed a full-text search using the q parameter. Place Rank is available on select places datasets, and is described in full below.

Blended Sorting

Blended sorting is the default behavior for Factual places data.

With standard sorts, you can specify secondary sorts to help break ties when sorting by your primary sort field. For example, if you sorted by region, you may find that you have hundreds of places in the same region, so you want all of the places within the same regions to be sorted by name:

sort=region:asc,name:asc

There are however times when what you want is a blending of your sort parameters. For example, Instead of sorting places by how close they are to you (and thus only returning the 20 closest businesses to you) you might want the 20 closest popular businesses near you. Factual’s API allows you to blend distance and Place Rank.

Examples:

sort={"placerank": 100,"distance": 50}
sort={"placerank":0,"distance":50}&q=sushi

In the examples above, the first example requests that you weight Place Rank 2 to 1 against distance. In the second example, the request is to sort by distance only. The difference between sort=$distance and the second example, is that distance will be weighed alongside full-text search in the second example.

The following are some rough guides for blending sorts:

Favor Popular Places (e.g., browser for places of interest around you)

sort={"distance":10,"placerank":1000}

Favor Close Places (e.g., search for places to “check in” to)

sort={"distance":1000,"placerank":100}

Place Rank

Place Rank is a machine-learned score ranking places based on their popularity. Factual uses Place Rank in conjunction with other algorithms to return more relevant results to our customers when they search for data using our API. The Place Rank algorithm uses many signals to determine the relative popularity of a place.

Existence

Existence is a machine-learned score, representing the likelihood that a place currently exists. Existence scores are a probability that the places exists, ranging from 0.0 (definitely does not exist) to 1.0 (definitely does). A place may have a low existence score for many reasons (this is not a comprehensive list):

You can manually choose the existence threshold you want to work with in the Read API using the threshold parameter. Options are comprehensive (allow lower existence scores), confident (only show places that are well verified), and default (a balance).