Introduction

The Crosswalk API enables you to map third-party (Yelp, Foursquare, etc.) identifiers for businesses or points of interest to each other where each ID represents the same place. The current list of supported namespaces is here.

Explore Crosswalk through our interactive demo.

Basic Syntax

Either pass a factual_id or a namespace/namespace_id pairing to find an entity to crosswalk. You can optionally restrict the results returned to be only for a specific namespace.

Examples

All examples below are shown with URL encoding for clarity. In practice, you will need to URL encode all GET parameters.

Return all third party IDs or URIs for The Stand using it's Factual ID:

Run example in Apigee - The Stand Factual endpoint

For the request above, ONLY return Loopt.com's identifier for The Stand:

Run example in Apigee - The Stand Loopt page

Return all third party IDs or URIs for The Stand using it's Foursquare ID:

Run example in Apigee - The Stand Foursquare endpoint

For the request above, ONLY return Yelp.com's identifier's for The Stand:

Run example in Apigee - The Stand Yelp page

Required Parameters

Parameter Name	Description	Example
KEY	Your API Key. Factual API key documentation is here.	KEY=Q3iBjOES4h1mZcNCZyBmQFcYREdjylIucvB3r2oI

NOTES:

During BETA, you need to request a key and secret directly from Factual.
Both the name of KEY parameter and the key passed into it are case-sensitive.
all examples are shown without URL Encoding for clarity.

Optional Parameters

NOTE: although these parameters are individually optional, at least one of the following paramater combinations is required:

factual_id
namespace and namespace_id

Parameter Name	Description	Example
factual_id	A Factual ID for an entity in the Factual places database	factual_id=0000022c-4ab3-4f5d-8e67-6a6ff1826a93
limit	The maximum rows to return. The default is 50. OAuth authentication is REQUIRED to exceed the default limit.	limit=100.
namespace	The namespace to search for a third party ID within. A list of currently supported services is here.	namespace=foursquare namespace=yelp
namespace_id	The id used by a third party to identify a place.	namespace_id=443338
only	Restrict the results to only return ids for the specified namespace(s)	only=fwix only=foursquare,yelp

NOTE:

All examples are shown without URL Encoding for clarity.
OAuth signing is optional for this request. If you do not sign your request, your request will be limited to system-wide defaults.

Responses

Successful Responses

Response Components

object	description
version	Version of the API that generated this response
response	Will return the number of rows in the included data packet and the reference data.
response.included_rows	The number of rows in the included data packet.
response.total_row_count	The total number of rows that fit your query. During beta, if total rows is greater than returned rows, there is significantly more data than expected and (likely) something is wrong.
response.data[]	An array of entities that conform to the specified parameters, sorted by namespace, followed by namespace_id
response.data[per entity].factual_id	The Factual ID for this entity.
response.data[per entity].url	A URL that relates directly to this entity.
response.data[per entity].namespace	The name of the service the URL for this entity relates directly to.
response.data[per entity].namespace_id	The system identifier (if available) used by the service specified by namespace.

Sample Successful Response

Error Responses

Crosswalk Specific Error Messages and Causes

In addition to general Factual API errors, the following errors may be returned in response to GET requests:

HTTP Error Code	Factual Error Type	Message	Cause
400	InvalidFilterArgument	This request requires at least one of the following parameters: 'factual_id', 'namespace'. Documentation: http://developer.factual.com	The request does not include either factual_id, or namespace.
400	InvalidFilterArgument	The 'namespace' parameter must be used in conjunction with the 'namespace_id' parameter. Documentation: http://developer.factual.com	The request includes namespace but does not also include namespace_id.

Places API - Crosswalk