Read


Use the read call to query from tables using any combination of full-text, parametric, or geo (lat/lng) searches.

Syntax

Reads are always implemented as a HTTP GET requests.

http://api.v3.factual.com/t/[table_id]/[factual_id]?select=[field names]&q=[search terms]&geo=[geo filter]&filters=[row filter]&threshold=[confident|default|comprehensive]&offset=[offset]&limit=[limit]&include_count=[true/false]&sort=[column:asc/desc|blending JSON]

  • To query for sets of data, specify any combination of full-text-search (q), geo, or row filters.
  • Offset and limit are supported for paging.
  • If you require a count of the total rows fitting our query, and don’t mind incurring the performance cost, specify include_count=true.

Examples

Find rows in the global places database in the United States:

http://api.v3.factual.com/t/places?filters={"country":"US"}

Get the row for Factual:

http://api.v3.factual.com/t/places/03c26917-5d66-4de9-96bc-b13066173c65

Find rows in the restaurant database whose names begins with the letters star (case insensitive) and return both the data and a total count of the matched rows:

http://api.v3.factual.com/t/restaurants-us?filters={"name":{"$bw":"star"}}&include_count=true

Do a full-text search of the restaurant database for rows that match the word coffee and the phrase los angeles:

http://api.v3.factual.com/t/restaurants-us?q=Coffee,"Los Angeles"

To support paging in your app, return rows 20-40 of the full-text search result above:

http://api.v3.factual.com/t/restaurants-us?q=Coffee,"Los Angeles"&offset=20&limit=20

Return rows from the global places database with a name equal to “Stand” within 5000 meters of the specified lat/lng:

http://api.v3.factual.com/t/places?filters={"name":"Stand"}&geo={"$circle":{"$center":[34.06018, -118.41835],"$meters": 2500}}

Parameters

Parameter Name Description Examples
filters Restrict the data returned to conform to specific conditions, e.g., “parametric search”. Documentation on filters is here.
filters={"last_name":"Smith"}
geo Restrict data to be returned to be within a geographical range based. Documentation on geo filters is here. Maximum value for $meters is 20000.
geo={"$circle":{"$center":[35.001,-18.221],"$meters": 5000}}
include_count Include a count of the total number of row counts returned. Requesting the row count will increase the time required to return a response. The default behavior is to NOT include a row count.
include_count=true
limit Maximum number of rows to return. Default is 20. The system maximum is 50. For higher limits please contact Factual, however consider requesting a download of the data if your use case is requesting more data in a single query than is required to fulfill a single end-user’s request.
limit=20
KEY Your API Key. The KEY parameter is only required for non-OAuthenticated requests, which are supported only as a debugging convenience.
KEY=Q3iBjOES4h1mZcNCZyBmQFcYREdjylIucvB3r2oI
offset Number of rows to skip before returning a page of data. Maximum value is 500 minus any value provided under limit. Default is 0.
offset=100
q Full text search query string. More information
q=Coffee Santa Monica 
q=Coffee,Tea
q="Father's Office"
select Only return specified fields
select=name,address
sort The field (or secondary fields) to sort data on, as well as the direction of sort. Alternately, a JSON map of blended sorting coefficients.

Sort options:
  • $distance supported as a sort option if a point/radius geo-filter is specified.
  • $relevance supported as a sort option if a full text search is specified either using the q parameter or using the $search operator in the filter parameter.
  • placerank is available for sorting places by popularity. Placerank should be sorted descending.
By default, data is sorted by distance and placerank blended at 1:1.
sort=name:asc
sort=region:asc,name:asc
sort=$distance
sort=placerank:desc
sort={"placerank":100,"distance":50} 
threshold Set a threshold for filtering on the level of confidence that Factual has that places exists. Valid values are confident, default, or comprehensive. If the threshold parameter is not specified, it uses the value default.
threshold=confident
user An arbitrary token for correlating read and boost requests to a single app/session/etc. Factual does not use this token to track users. The function of this information is to help evaluate boosts based on the related searches. More information
user=32EC2020-3AEA-1069-A2DD-08002B30309D

The q parameter enables full-text search across all the fields of a Factual table. Unlike row filters (using comparison operators like equals or begins with), full-text search more loosely matches the provided search terms against rows in the Factual table. For example, a search for Bar may bring up rows that include the term bar, bars, barred or (potentially) beer.

Examples:
    q=hot dogs (Must have the word hot and the word dogs, but not necesarily in that order, or in a single field.)
    q=sushi, sashimi (Must have either the word sushi or or the word sashimi.)
    q="santa monica" (Must have the phrase santa monica with both terms in that order, in a single field.)

Row filters

Row filters enable parametric searches. Row filters enable you to selectively filter read API requests to only data which fits constraints defined in your filters query parameter, similar to the where clause of a SQL query. Factual row filters are implemented as JSON.

Comparison operators

Comparison operators map field names to a map of an operator, and the appropriate parameters for the operator.

Operator Description Operates on Datatype of Field… Examples
$blank test to see if a value is blank (or null) text,numeric
filters={"tel":{"$blank":true}} (find rows with missing telephone numbers)
filters={"tel":{"$blank":false}} (find rows with non-blank telephone numbers)
$bw begins with text
filters={"name":{"$bw":"b"}}
$bwin begins with any of text
filters={"name":{"$bwin":["lt", "sg", "cpt"]}}
$eq equal to text,numeric
filters={"region":{"$eq":"CA"}} or {"region":"CA"} (acceptable shorthand)
$excludes array does not include multivalued text, numeric
filters={"category_ids":{"$excludes":9}}
$excludes_any array does not include any of multivalued text, numeric
filters={"category_ids":{"$excludes_any":[318,321]}}
$gt greater than numeric
filters={"rating":{"$gt":7.5}}
$gte greater than or equal to numeric
filters={"rating":{"$gte":7.5}}
$in equals any of text,numeric
filters={"region":{"$in":["MA","VT","NH","RI","CT"]}}
$includes array includes multivalued text, numeric
filters={"category_ids":{"$includes":10}}
$includes_any array includes any of multivalued text, numeric
filters={"category_ids":{"$includes_any":[10,100]}}
$lt less than numeric
filters={"age":{"$lt":50}}
$lte less than or equal to numeric
filters={"age":{"$lte":7.5}}
$nbw does not begins with text
filters={"name":{"$nbw":"Mr."}}
$nbwin does not begin with any of text
filters={"class":{"$nbwin":["beginner", "intermediate"]}}
$neq not equal to text,numeric
filters={"region":{"$neq":"CA"}}
$nin does not equal any of text,numeric
filters={"locality":{"$nin":["Los Angeles","Santa Monica"]}}
$search full-text search a field text
filters={"name":{"$search":"Charles"}}

Logical operators

Multiple row filters can be logically combined using the $and and $or operators.

AND

The $and operator accepts a JSON array of row filters. For example:

filters={"$and":[{"name":{"$bw":"McD"},"category_ids":{"$includes":338}}]}

will return rows where both name begins with McD AND category_ids includes 338 (Food & Dining):

OR

Similar to the $and operator, the $or operator accepts a JSON array of row filters:

filters={"$or":[{"tel":{"$blank":true}},{"tel":{"$bw":"(212)"}}]}

will return rows where either tel is either blank OR starts with (212):

Combined ANDs and ORs

$and and $or can be combined:

filters={"$and":[{"first_name":"Suzy"},{"$or":[{"last_name":"Q"},{"last_name":{"$blank":true}}]}]}

Full-text-search operator

The $search operator enables making a full-text search on a single field. When using the $search operator.

Geo filters

Geo filters enable read requests to return only data bounded by specified geographic coordinates for tables that support it. The Factual read and facet API methods accept geo filters specified in a JSON format (described below) using the geo parameter.

Examples:

Find all rows within a specified radius of a geo point:

http://api.v3.factual.com/t/restaurants-us?geo={"$circle":{"$center":[34.06021,-118.41828],"$meters": 5000}}

  • When using a point/radius geo filter, distance (in meters) from the point will be returned in the response packet under the $distance key. This distance is calculated as the crow flies.
  • Point/radius queries are implemented as a point at the center of a square with sides twice the radius.
  • The radius for point/radius queries should be limited to 15 km.

Find the closest places to a specified point:

http://api.v3.factual.com/t/places?geo={"$point":[34.06021,-118.41828]}

  • Note, the above method will limit results to within 500 meters of the specified point.

Find places within a rectangular bounding box (points are [top,left],[bottom,right]):

http://api.v3.factual.com/t/places?geo={"$within":{"$rect":[[34.06110,-118.42283],[34.05771,-118.41399]]}}

A couple general notes on geo filters:

  • Points are always ordered as [latitude, longitude].
  • Distance is specified in meters.
  • The maximum area that any geo query can encompass is 900 km2

Boost


The Boost API enables you to signal to Factual that a specific row returned by any read API call should be a prominent result for the associated search.

Boost does not currently generate a real-time optimization of search, nor does it enable per-user customized search responses. Boost signals are periodically evaluated and applied to overall search optimization in the Factual read API by way of PlaceRank.

Syntax

Boost calls are always implemented as a HTTP POST requests. It is required that you set the Content-Type header of your HTTP POST Submit request to application/x-www-form-urlencoded. Naturally, this implies you must also URL encode all parameters in the POST body.

factual_id=[Factual Id]&q=[full-text-search query]&user=[user token]

Examples

POST /t/places-us/boost HTTP/1.1
Host: api.v3.factual.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 84
-
factual_id=03c26917-5d66-4de9-96bc-b13066173c65&q=local+business+data&user=user12345

Parameters

Parameter Name Description Examples
factual_id The Factual ID of an entity that should be boosted in search results. factual_id=03c26917-5d66-4de9-96bc-b13066173c65
KEY Your API Key. The KEY parameter is only required for non-OAuthenticated requests, which are supported only as a debugging convenience.
KEY=Q3iBjOES4h1mZcNCZyBmQFcYREdjylIucvB3r2oI
lat (Optional) latitude of the location where this result was queried for lat=34.058743
lng (Optional) longitude of the location where this result was queried for lat=-118.41694
q (Optional) full-text-search query parameter value for q from a prior read request.
q=Coffee Santa Monica 
q=Coffee,Tea
query_timestamp (Optional) Unix timestamp corresponding to the date/time the search request was made. This is provided for use cases where boosts are being post-processed in regards to the original search queries. query_time=1397564362
user An (optional) arbitrary token for correlating read and boost requests to a single app/session/etc. Factual does not use this token to track users. The function of this information is only to help evaluate how a boost relates to a search.
user=21EC2020-3AEA-1069-A2DD-08002B30309D
User parameter

The Factual read and Boost API calls accept a user parameter. This parameter is simply any token that can be used to help guide that sets of calls as having from a single user, app, process, etc. The purpose of the user parameter is to help Factual sort out how read and boost calls in tandem signify intent and success (or lack therein) towards finding the “right” results. There are no constraints on how you utilize the user parameter. For example, any of the following are appropriate tokens:

  • Your Factual username (if you are just showing that all of the reads and boosts are from your app, without any granularity)
  • An anonymized GUID or some other deterministic hash value representing the user in your application that is making search requests
  • A random token generated at the time a read API call is made, and forgotten when a corresponding boost has been sent.

Schema


This method returns the schema for a Factual table view. The schema includes:

  • Table view meta-data: name, description, list of fields, schema version, and whether or not the table is geo and/or full-text searchable.
  • Field meta-data (for each field): name, optional aliase(s), datatype, whether the field is supports full-text search, facets or writes.

Syntax

A GET request with the proper table view Id will fetch the table schema:

http://api.v3.factual.com/t/[view id]/schema

Examples

Get the schema of the Global places table:

http://api.v3.factual.com/t/places/schema

Get the schema of the US restaurants table:

http://api.v3.factual.com/t/restaurants-us/schema

Parameters

Parameter Name Description Example
KEY Your API Key. The KEY parameter is only required for non-OAuthenticated requests, which are supported only as a debugging convenience.
KEY=Q3iBjOES4h1mZcNCZyBmQFcYREdjylIucvB3r2oI

Facets


The facets API call enables your to return row counts for Factual tables, grouped by facets of the data. For example, you may want to query all businesses within 1 mile of a location and for a count of those businesses by category.

Not all fields are configured to return facet counts. To determine what fields you can return facets for, use the schema call. The faceted attribute of the schema will let you know.

Syntax

Facet calls are performed as HTTP GET requests:

http://api.v3.factual.com/t/[table_name]/facets?select=[field1,field2...]&q=[full-text-search]&filters=[JSON row filters]&geo=[JSON geo-filter]&min_count=[minimum count to show]

Examples

Return a count of Starbucks by country:

http://api.v3.factual.com/t/places/facets?select=country&q=starbucks

Count Starbucks in the US by city and state:

http://api.v3.factual.com/t/places/facets?select=locality,region&q=starbucks&filters={"country":"US"}

Count businesses by category id 5 km around Factual:

http://api.v3.factual.com/t/places/facets?select=category_ids&geo={"$circle":{"$center":[34.06018, -118.41835],"$meters": 5000}}

Parameters

Parameter Name Description Examples
filters Restrict the data returned to conform to specific conditions, e.g., “parametric search”. Documentation on filters is here.
filters={"last_name":"Smith"}
geo Restrict data to be returned to be within a geographical range based. Documentation on geo filters is here. Maximum value for $meters is 20000.
geo={"$circle":{"$center":[35.001,-18.221],"$meters": 5000}}
KEY Your API Key. The KEY parameter is only required for non-OAuthenticated requests, which are supported only as a debugging convenience.
KEY=Q3iBjOES4h1mZcNCZyBmQFcYREdjylIucvB3r2oI
include_count Include a count of the total number of row counts returned. Requesting the row count will increase the time required to return a response. The default behavior is to NOT include a row count.
include_count=true
limit Maximum number of facet counts to return in the response. Default is 20. Max is 50.
limit=20
min_count For each facet count, the minimum count it must show in order to be returned in the response. Must be zero or greater. The default is 1.
min_count=1
q Full text search query string. Documentation for search filters are here
q=Coffee Santa Monica
q=Coffee,Tea
threshold Set a threshold for filtering on the level of confidence that Factual has that places exists. Valid values are confident, default, or comprehensive. If the threshold parameter is not specified, it uses the value default.
threshold=confident

Aside from min_count, all of the parameters above are identical to the same-named parameters in the read
API call.

Submit


This method enables submitting edits to existing rows and/or submitting new rows of data in Factual tables. For information on deleting records, see flag. For information on removing data from a single attribute of an existing row of data, see clear.

Submit Endpoint

You may upsert with or without the factual_id. Include the factual_id to update an extant entity. Do not include the ID if you are attempting to write a new entity, or do not know if one already exists.

Please use the us-sandbox table for testing submissions.

Without the Factual ID

Submit to the table name only, in this case, the places table:

http://api.v3.factual.com/t/places/submit

With the Factual ID

Include the Factual ID in the URL. When employing the Factual id, the table name (in this case, places) is also required. Do NOT include the Factual id in the values parameter- it will be ignored.

http://api.v3.factual.com/t/places/03c26917-5d66-4de9-96bc-b13066173c65/submit

Examples

Submit is always performed as an HTTP POST. The values and user parameters should be passed in as URL Encoded content to the POST body. You MUST set the content-type to application/x-www-form-urlencoded.

Add data to the Factual places table

If the data provided matches an existing place in our data, your data will be merged into the existing one as appropriate.

POST /t/us-sandbox/submit HTTP/1.1
Host: api.v3.factual.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 145
-
values=%7B%22name%22%3A%22Factual%20North%22%2C%22address%22%3A%221%20North%20Pole%22%2C%22latitude%22%3A90%2C%22longitude%22%3A0%7D&user=my_user


Correct the longitude in a record
POST /t/us-sandbox/21EC2020-3AEA-1069-A2DD-08002B30309D/submit HTTP/1.1
Host: api.v3.factual.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 52
 
values=%7B%22longitude%22%3A0.000500%7D&user=factual


More examples

In addition to the examples above, there are place-specific examples in our Write API guide.

Parameters

Parameter Name Description Examples
clear_blanks If set to true (default is false) any field hashed to "" will be accompanied with a clear.
clear_blanks=true
comment Any english text comment that may help explain your corrections.
comments=Just visited first hand.
strict Enable strict mode (strict=true). See below.
strict=true
reference A reference to a URL, title, person, etc. that is the source of this data.
reference=http://coolrestaurantsite.com
user* Any string corresponding to the user submitting the data. The user parameter is described in detail below.
user=my_user_name
user=423
user=21EC2020-3AEA-1069-A2DD-08002B30309D}
values* A JSON hash field names and values to be added to a Factual table
{"name":"McDenny’s","address":"1 Main St.","locality":"Bedrock","region":"BC"}

Required*

User parameter

Factual data submissions are given attribution on a per user basis, however your application’s user database is opaque to Factual. Having user attribution is important in that it is used to disambiguate whether or not a number of corrections from a single API key are intended to overwrite each other versus to be weighed against similar data from each individual user of the application using that key. The user parameter enables you to guide Factual on how to evaluate your data. There are no constraints on how you utilize the user parameter. For example, any of the following are appropriate user strings:

  • Your Factual username, if the intent is that all data came from you, personally
  • The username of the user in your application that submitted the data
  • An internal ID associated with the user in your application that submitted the data
  • An GUID or some other deterministic hash value representing the user in your application that submitted the data
strict mode

By default, Factual’s API will optimistically accept all field provided in the values parameter- with the exception of fields that have explicitly been marked as unwriteable. This makes it easier to simply pass what data you have to Factual, regardless of how precisely well it fits the schema of the table you are correcting.

A potential downside of this is that you will not be warned if data you are providing may be discarded due to simple mismatches between field names, and what you’ve put in your values parameter. For example, if you misspell “category” as “catogory”. Setting the strict parameter to true will cause the system to automatically verify the attribute names of the values you submit against the Factual schema. Any fields that do not match will cause the entire submission to automatically be rejected with a 400 error.

clear_blanks

Using clear_blanks=true, updates to fields and clearing of fields can be accomplished in a single API call. For example:

POST /t/places-us/21EC2020-3AEA-1069-A2DD-08002B30309D/submit 
HTTP/1.1 Host: api.v3.factual.com 
Content-Type: application/x-www-form-urlencoded 

user=factual&values={"address":"1 main street","address_extended":""}&clear_blanks=true

will behave identically to sending a submit request with the address and a clear request for the address_extended, to update the address and remove the existing extended address.

Flag


This method enables flagging problematic rows in Factual tables. Use this method if you are requesting for an entity to be deleted or merged into a duplicate record.

Syntax

Flag API calls are always performed as HTTP POST requests. It is required that you set the Content-Type header of your HTTP POST Submit request to application/x-www-form-urlencoded. Naturally, this implies you must also URL encode all parameters in the POST body.

problem=[problem type]&user=[user token]&fields=[optional JSON array]&preferred=[optional factual id]&reference=[optional string]&comment=[optional string]

Examples

Report that the entity 21EC2020-3AEA-1069-A2DD-08002B30309D in the places table is a duplicate of another row. The other row (0656a5d0-cc2b-4fef-9206-f8d9f07b0220) is the preferred row:

POST /t/us-sandbox/21EC2020-3AEA-1069-A2DD-08002B30309D/flag HTTP/1.1
Host: api.v3.factual.com 
Content-Type: application/x-www-form-urlencoded
Content-Length: 79
 
problem=duplicate&user=a_user_id&preferred=0656a5d0-cc2b-4fef-9206-f8d9f07b0220

Report that entity 21EC2020-3AEA-1069-A2DD-08002B30309D has been relocated. 0656a5d0-cc2b-4fef-9206-f8d9f07b0220 is the new location:

POST /t/us-sandbox/21EC2020-3AEA-1069-A2DD-08002B30309D/flag HTTP/1.1
Host: api.v3.factual.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 79

problem=relocated&user=a_user_id&preferred=0656a5d0-cc2b-4fef-9206-f8d9f07b0220

Report that you think that entity 21EC2020-3AEA-1069-A2DD-08002B30309D appears to be spam:

POST /t/us-sandbox/21EC2020-3AEA-1069-A2DD-08002B30309D/flag HTTP/1.1
Host: api.v3.factual.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 27
 
problem=spam&user=a_user_id

Report that the entity 21EC2020-3AEA-1069-A2DD-08002B30309D is incomplete without it’s lat/lng:

POST /t/us-sandbox/21EC2020-3AEA-1069-A2DD-08002B30309D/flag HTTP/1.1 
Host: api.v3.factual.com 
Content-Type: application/x-www-form-urlencoded
Content-Length: 64
 
problem=spam&user=a_user_id&comment=This+row+has+no+lat+and+long

Report that the category for entity 21EC2020-3AEA-1069-A2DD-08002B30309D appears to be incorrect:

POST /t/us-sandbox/21EC2020-3AEA-1069-A2DD-08002B30309D/flag HTTP/1.1 
Host: api.v3.factual.com 
Content-Type: application/x-www-form-urlencoded
Content-Length: 89

problem=inaccurate&fields=%5Bcategory_ids%5D&comment=Should+be+a+car+wash&user=me

Parameters

Parameter Name Description Examples
comment A comment that helps explain the problem
comment=Place+was+bulldozed+to+the+ground.
fields JSON array of any fields that should be examined with respect to the identified problem.
fields=["lat","lng"]
fields=["name"]
preferred Optional Factual Id representing the preferred row to preserve when reporting a relocated or duplicate place.
preferred=0656a5d0-cc2b-4fef-9206-f8d9f07b0220
problem* One of: closed, duplicate, inaccurate, inappropriate, nonexistent, relocated, spam, or other as explained below.
problem=duplicate
problem=inaccurate
reference A citation to information that may illuminate the problem.
reference=http://somesite.com
reference=Fodor’s guide
reference=I’m the owner
user* An arbitrary token representing the user contributing the data. The user parameter is described in detail below.
user=my_user_name
user=423
user=21EC2020-3AEA-1069-A2DD-08002B30309D

Required*

User parameter


see User parameter under Submit

Clear


This method enables clearing existing attributes in an entity. Clearing an attribute attempts to reset whatever value it currently contains, to a blank state.

Syntax

By its nature, clear only operates on existing entities. As such, clear requests must have the Factual Id of the entity in the request URL. For example:

http://api.v3.factual.com/t/[view id]/[factual id]/clear

Examples


Clear the extended address for a place
POST /t/us-sandbox/21EC2020-3AEA-1069-A2DD-08002B30309D/clear HTTP/1.1
Host: api.v3.factual.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 40
 
fields=address_extended&user=my_username


Clear both the latitude and longitude for a place
POST /t/us-sandbox/21EC2020-3AEA-1069-A2DD-08002B30309D/clear HTTP/1.1
Host: api.v3.factual.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 40
 
fields=latitude,longitude&user=some_user


More Examples

In addition to the examples above, there are place-specific examples in our Write API guide.

Parameters

Parameter Name Description Examples
user* Any string corresponding to the user submitting the data. The user parameter is described in detail below.
user=my_user_name
user=423
user=21EC2020-3AEA-1069-A2DD-08002B30309D}
fields* A field or comma delimited list of fields to be cleared.
fields=address_extended
fields=latitude,longitude

Required*

User parameter

see User parameter under Submit

Match


Match your data to Factual’s. The Factual Match endpoint will simply return the Factual ID of the data that matches your data; we return no data if we cannot identify your entity unequivocally.

If you require both the Factual ID and entity data for the place, see Resolve.

Syntax

Pass what you know to Factual Match via a GET request, with the attributes included as JSON-encoded key/value pairs.

http://api.v3.factual.com/t/[view name]/match?values=[JSON hash]

Examples

Find the entity named “McDonald’s” with an address combination

http://api.v3.factual.com/t/places-us/match?values={"name":"McDonalds","address":"10451 Santa Monica Blvd","region":"CA","postcode":"90025"}

Find the entity named “McDonald’s” with only a specified lat/lng

http://api.v3.factual.com/t/places-us/match?values={"name":"McDonalds","latitude": 34.05671,"longitude":-118.42586}

We accept any Global Local parameters in most combinations; some combinations of parameters will be encountered more frequently than others, and have therefore consumed the respective proportion of our beta development efforts.

Match is designed to work with whatever you throw at it, but the more parameters you provide, the better we can match your attributes to an entity. Give us what you got!

Parameters

Parameter Name Description Examples
KEY Your API Key. The KEY parameter is only required for non-OAuthenticated requests, which are supported only as a debugging convenience.
KEY=Q3iBjOES4h1mZcNCZyBmQFcYREdjylIucvB3r2oI
values A JSON hash of key value pairs representing the data that will be matched against.
values={"name":"McDonalds","address":"10451 Santa Monica Blvd","locality":"Los Angeles","region":"CA"}
values={"name":"McDonalds","latitude":34.05671,"longitude":-118.42586}

Successful Call, Matched

In this example, Match has determined that a single, suitable candidate meets the criteria you passed to the platform. The response will contain ONLY the Factual ID of the match. Match will never return more than one matched record.

{
  "version":3,
  "status": "ok",
  "response": 
  {
    "data": 
    [
      {
      "factual_id": "bd886f67-9d86-40c5-9217-f7bcd53cfc0e"
      }
    ],
    "included_rows": 1
  }
}

Successful Call, Unmatched

If Match cannot match your data to an exact record, no data will be returned:

{
  "version": 3,
  "status": "ok",
  "response": {
    "data": [],
    "included_rows": 0
   }
} 

Resolve


Use Resolve to enrich your data and match it against Factual’s. For simply mapping your data to Factual’s, see Match.

Syntax

Pass what you know to Factual Resolve via a GET request, with the attributes included as JSON-encoded key/value pairs.

http://api.v3.factual.com/t/[view name]/resolve?values=[JSON hash]&debug=[true|false]

Examples

Find the entity named “McDonald’s” with an address combination

http://api.v3.factual.com/t/places-us/resolve?values={"name":"McDonalds","address":"10451 Santa Monica Blvd","region":"CA","postcode":"90025"}

Find the entity named “McDonald’s” with only a specified lat/lng

http://api.v3.factual.com/t/places-us/resolve?values={"name":"McDonald's","longitude":-118.472964,"latitude":34.033996}

Parameters

Parameter Name Description Examples
values* A JSON hash of key value pairs representing the data that will be matched against.
values={"name":"McDonalds","address":"10451 Santa Monica Blvd","locality":"Los Angeles","region":"CA"}
values={"name":"McDonalds","latitude":34.05671,"longitude":-118.42586}
debug Optionally enables toggling on a debug mode for Resolve that returns all potential candidates for resolution and meta-data regarding resolution quality.
debug=true
debug=false

We accept any Global Local parameters in most combinations; some combinations of parameters will be encountered more frequently than others, and have therefore consumed the respective proportion of our beta development efforts.

Match is designed to work with whatever you throw at it, but the more parameters you provide, the better we can match your attributes to an entity. Give us what you got!

Successful Call, Matched

In this example, Resolve has determined that a single, suitable candidate meets the criteria you passed to the platform. The response will contain that candidate and ONLY that candidate. Resolve will never return more than one matched record, unless the debug flag has been invoked. To support legacy behavior, the parameter resolved:true will always be included in the single returned row.

{
  "version":3,
  "status": "ok",
  "response": 
  {
    "data": 
    [
      {
      "factual_id": "bd886f67-9d86-40c5-9217-f7bcd53cfc0e",
      "name": "McDonald's",
      "address": "10451 Santa Monica Blvd",
      "locality": "Los Angeles",
      "region": "CA",
      "country": "US",
      "postcode": "90025",
      "tel": "(310) 474-3160",
      "category": "Food & Beverage > Restaurants > Fast Food",
      "website": "http://mcdonalds.com/",
      "latitude": 34.056555,
      "longitude": -118.425755,
      "status": "1"
      "resolved":true
       }
    ],
    "included_rows": 1
  }
}

Successful Call, Unmatched

If Match cannot match your data to an exact record, no data will be returned:

{
  "version": 3,
  "status": "ok",
  "response": {
    "data": [],
    "included_rows": 0
   }
} 

Debug Parameter

If you pass the debug flag (=true) within a Resolve call, you will receive a list of candidates (if any) that were returned as likely matches to your criteria, ordered by similarity. Similarity ranges from 1.0 (high quality match) to .2 (low quality). If any of the candidates was deemed to be a suitable match, it will include the parameter resolved:true. Each non-matched candidate will include resolved:false.

{
  "version":3,
  "status": "ok",
  "response": 
  {
    "data": 
    [
      {
      "factual_id": "dab0005d-21d5-4c48-a9d6-02daa00479d3",
      "name": "Warszawa",
      "address": "1414 Lincoln Blvd",
      "locality": "Santa Monica",
      "region": "CA",
      "country": "US",
      "postcode": "90401"
      "tel: "(310) 393-8831"
      "category": "Food & Beverage > Restaurants"
      "latitude": 34.019207
      "longitude": -118.49102
      "status": "1",
      "resolved":true,
      "similarity":.99
      },
      {
      "factual_id": "dc8Defe7-d54c-2123-ede9-19abc220004e",
      "name": "Warszawa Backyard Bar",
      "address": "1414 Lincoln Blvd",
      "locality": "Santa Monica",
      "region": "CA",
      "country": "US",
      "postcode": "90401"
      "tel: "(310) 393-8831"
      "category": "Arts, Entertainment & Nightlife > Bars"
      "latitude": 34.019206
      "longitude": -118.49100
      "status": "1",
      "resolved":false,
      "similarity":.98
      }
    ],
    "included_rows": 2
  }
}

Multi


The multi API request enables making multiple API requests on the same connection.

Syntax

The multi request should be using HTTP GET:

http://api.v3.factual.com/multi?queries=[JSON hash]

Examples

http://api.v3.factual.com/multi?queries={
 "query1":"/t/places?filters={"factual_id":"91ce2888-a13e-43ac-9bb8-f18eaedccabf"}",
 "query2":"/t/crosswalk/91ce2888-a13e-43ac-9bb8-f18eaedccabf"
}

A couple of important notes:

  • Each request being passed into the queries parameter must be treated as an independent request. This means that you must properly URL encode each request before you add it to the queries hash. See the encoding section, below.
  • Multi must always be performed as a HTTP GET request and can only be used with API calls performed as GET requests.
  • Each request in a multi call is made asynchronously of the other calls in the multi call. HOWEVER, multi requests are not returned until all of the contained calls are complete.
  • The maximum number of requests that can be performed by a multi call is 3. If you require more than this default, please contact us to inquire about premium access. Keep in mind that, because the response is blocked by the slowest request to complete, higher numbers of contained requests may risk periodic poor performance.
  • Each query requires a hash key (e.g., “query1” and “query2”, above). These are arbitrarily defined by you, and are returned in the result to allow you to differentiate the results of each.
  • If you are debugging with the KEY parameter, you do not need to specify the KEY parameter for each query inside the queries hash. Specify the KEY parameter for the multi call. E.g., /multi?KEY=…&queries={…}

Parameters

Parameter Name Description Example
KEY Your API Key. The KEY parameter is only required for non-OAuthenticated requests, which are supported only as a debugging convenience.
KEY=Q3iBjOES4h1mZcNCZyBmQFcYREdjylIucvB3r2oI
queries* A JSON hash containing all queries that are to be run, mapped to a key that will be used to map each individual response in the full response.

Required*

Encoding


The mutli API call requires double-encoding. First, all of the parameters of the subqueries must be encoded. Then, as a second pass, the queries parameter must be encoded.


For example, if you are trying to perform a multi on the following two API calls:

http://api.v3.factual.com/t/places?filters={"postcode":"90067"}
http://api.v3.factual.com/t/places/facets?filters={"postcode":"90067"}&select=category


First, encode each of the API calls:

/t/places?filters=%7B%22postcode%22%3A%2290067%22%7D
/t/places/facets?filters=%7B%22postcode%22%3A%2290067%22%7D&select=category


Then take the encoded queries (minus the domain portion of the URL) and put them into the queries parameter:


http://api.v3.factual.com/multi?queries={
"get-postcode":"/t/places?filters=%7B%22postcode%22%3A%2290067%22%7D",
"get-facet":"/t/places/facets?filters=%7B%22postcode%22%3A%2290067%22%7D&select=category"
}

Finally, URL encode the entire queries parameter:

http://api.v3.factual.com/multi?queries=%7B%22get-postcode%22%3A%22%2Ft%2Fplaces%3Ffilters%3D%257B%2522postcode%2522%253A%252290067%2522%257D%22%2C%22get-facet%22%3A%22%2Ft%2Fplaces%2Ffacets%3Ffilters%3D%257B%2522postcode%2522%253A%252290067%2522%257D%26select%3Dcategory%22%7D

Diffs


Factual makes available data downloads — the entirety of a table in zipped CSV format. While data downloads implemented on your own servers are highly convenient for some use cases, they divorce your copy of the data from our continuously updated canonical dataset. In contract, users of the Factual API always have access to the freshest possible data.

The Factual Diffs API solves this issue by perpetuating atomic changes to the Factual dataset, disconnecting your update schedule from our own and guaranteeing a current and timely implementation of Factual data on your local server.

Note: the Diffs API is only available to users with download licenses. Please contact Factual if you are interested in using this API.

Syntax

Our API server allows you to connect via HTTP GET while specifying a view (usually a table) to which you wish to subscribe as well as a start date and end date:

http://api.v3.factual.com/t/[ViewName]/diffs?start=[timestamp]&end=[timestamp]

Examples

Request all diffs from the US Places dataset that were generated in a for window of just over 24 minutes on Fri, 07 Dec 2012 13:41:03 -0800

http://api.v3.factual.com/t/places-us/diffs?start=1354916463822&end=1354917903834

Request all diffs from the US Restaurants dataset for the same window as above.

http://api.v3.factual.com/t/restaurants-us/diffs?start=1354916463822&end=1354917903834

Parameters

Parameter Name Description
start beginning of window to pull down diffs. Unix timestamp in milliseconds
end end of window to pull down diffs. As above.

Note: The maximum duration for a single diffs call is a single day (86,400 seconds). E.g., end – start must be less than 86,400.

Responses

The JSON result is not a single block of JSON data but rather discreet chunks of atomic JSON, each one describing an operation against a single entity. Each operation is on a single line; use line breaks to divide each response into individual operations.

payload

All attributes of the entity returned in the payload attribute. Included in INSERT and UPDATE actions only.

timestamp

A Unix Timestamp in milliseconds.

This value represents the currency of the record – when it was last updated. If the record has not been updated since it was created, the timestamp records the creation date; where a record is being deprecated or deleted, the timestamp notes when the entity was deprecated/deleted.

Because Factual pushes out multiple changes in the same second, we require milliseconds to provide a greater degree of control over the resolution of the request window. Millisecond Unix timestamps (in ‘epoch time’) look like 1326754278000; although we expect users to store the latest timestamp from the previous request, this utility may offer some assistance should converting from human-readable formats be required.

Forthcoming Factual data dumps will include the timestamp for reference; please contact us if you wish to update a previous data version and we will advise on the timestamp.

type

The type of change: insert (new entity), update (one or many attributes of the entity were modified), deprecate (entire entity replaced by another) or delete (entity removed).

replaced_by

Deprecated records include the Factual ID of the replacement entity in the ‘replaced_by’ attribute. Included in deprecate diff events only.

changed

Updated records include a JSON array containing the names of the changed fields have changed. Included in update diff events only.

Processing diffs

You should generally assume that any data returned from a diffs call be handled idempotently. Updated records will always contain the whole of the updated record. If you have to backtrack on your diffs time range, you may be inserting rows that already exist in your database. As a rule, you should assume that any insert might need to be handled as an update or that a delete may attempt to delete a row you have already deleted.

Geocode

A reverse geocoder: you provide us with a longitude and latitude, we’ll return the nearest valid address.

Caveats:

  • The service is most accurate and inclusive in the US
  • Addresses will not be returned where we do not have supporting, address-level data
  • This service finds the nearest address – this may-or-may-not be a business. To find the nearest business, use our Global Places API

Syntax

Geocode requests should be made as HTTP GET requests:

http://api.v3.factual.com/places/geocode?geo=[JSON point]

Examples

Find the closest address to a latitude 34.06021, longitude -118.41828:

http://api.v3.factual.com/places/geocode?geo={"$point":[34.06021,-118.41828]}

Parameters

Parameter Name Description Examples
geo* A geographic point. Coordinate order is latitude, longitude.
geo={"$point":[34.06021,-118.41828]}
KEY Your API Key. The KEY parameter is only required for non-OAuthenticated requests, which are supported only as a debugging convenience.
KEY=Q3iBjOES4h1mZcNCZyBmQFcYREdjylIucvB3r2oI

Required*