Skip to main content

Foursquare Data Source

Follow the instructions below to create a new data flow that ingests data from a Foursquare source in Nexla.
foursq_api.png

Foursquare

Create a New Data Flow​

  1. To create a new data flow, navigate to the Integrate section, and click the New Data Flow button. Then, select the desired flow type from the list, and click the Create button.

  2. Select the Foursquare connector tile from the list of available connectors. Then, select the credential that will be used to connect to the Foursquare instance, and click Next; or, create a new Foursquare credential for use in this flow.

  3. In Nexla, Foursquare data sources can be created using pre-built endpoint templates, which expedite source setup for common Foursquare endpoints. Each template is designed specifically for the corresponding Foursquare endpoint, making source configuration easy and efficient.
    • To configure this source using a template, follow the instructions in Configure Using a Template.

    Foursquare sources can also be configured manually, allowing you to ingest data from Foursquare endpoints not included in the pre-built templates or apply further customizations to exactly suit your needs.
    • To configure this source manually, follow the instructions in Configure Manually.

Configure Using a Template​

Nexla provides pre-built templates that can be used to rapidly configure data sources to ingest data from common Foursquare endpoints. Each template is designed specifically for the corresponding Foursquare endpoint, making data source setup easy and efficient.

Endpoint Settings​

  • Select the endpoint from which this source will fetch data from the Endpoint pulldown menu. Available endpoint templates are listed in the expandable boxes below. Click on an endpoint to see more information about it and how to configure your data source for this endpoint.

    Search for Venues Near Location

    Returns a list of venues near the geocodable location, optionally matching a search term. Returns a failed_geocode error if the location string is not geocodable.

    • Enter a geocodable location string in the Search Near Location (Geocodable String) field. This should be a string naming a place in the world (e.g., "New York, NY" or "1600 Amphitheatre Parkway, Mountain View, CA"). The API will search within the bounds of the geocode and add a geocode object to the response.

    • Select your intent in performing the search from the Intent dropdown menu. Available options are: checkin (default), global, browse, or match. The default value is checkin if not specified.

    • Optionally, enter a search term to be applied against venue names in the Search Query(Optional) field. This allows you to filter venues by name. The default value is empty if not specified.

    • The endpoint uses GET requests to https://api.foursquare.com/v2/venues/search?limit=50&near={near_string}&intent={intent}&query={query}&v=20200324&client_id={client_id}&client_secret={client_secret} where {near_string} is the Search Near Location, {intent} is the Intent, {query} is the Search Query, {client_id} is your Client ID from the credential configuration, and {client_secret} is your Client Secret from the credential configuration. The endpoint URL is automatically constructed based on the Foursquare API base URL and all the parameters.
    • The endpoint does not use pagination and returns up to 50 venues in a single request.
    • The endpoint will return a list of venues near the specified location. The response data is extracted from the venues array in the API response ($.response.venues[*]), with each venue record processed individually.

    Location strings should be geocodable place names or addresses. The API will attempt to geocode the location string and search for venues within the geocoded area. If the location string cannot be geocoded, the API will return a failed_geocode error. The Intent parameter determines how the search is performed: checkin finds venues suitable for check-ins, global searches globally, browse searches within a specific area, and match attempts to match a specific venue. The endpoint uses a static URL (iteration.type: static.url) and does not require pagination. The response data path is $.response.venues[*], which extracts all items from the venues array in the API response. For detailed information about searching for venues, see the Foursquare Places API documentation.

    Search for Venues Near Lat, Long

    Returns a list of venues near the specified latitude & longitude, optionally matching a search term.

    • Enter a comma-separated latitude and longitude in the Search Near Lat,Long field. This should be in the format latitude,longitude (e.g., 40.74224,-73.99386).

    • Select your intent in performing the search from the Intent dropdown menu. Available options are: checkin (default), global, browse, or match. The default value is checkin if not specified.

    • Optionally, enter a search term to be applied against venue names in the Search Query(Optional) field. This allows you to filter venues by name. The default value is empty if not specified.

    • The endpoint uses GET requests to https://api.foursquare.com/v2/venues/search?limit=50&near={ll}&intent={intent}&query={query}&v=20200324&client_id={client_id}&client_secret={client_secret} where {ll} is the Search Near Lat,Long, {intent} is the Intent, {query} is the Search Query, {client_id} is your Client ID from the credential configuration, and {client_secret} is your Client Secret from the credential configuration. The endpoint URL is automatically constructed based on the Foursquare API base URL and all the parameters.
    • The endpoint does not use pagination and returns up to 50 venues in a single request.
    • The endpoint will return a list of venues near the specified coordinates. The response data is extracted from the venues array in the API response ($.response.venues[*]), with each venue record processed individually.

    Latitude and longitude values should be in decimal degrees format, with latitude first, followed by a comma, then longitude (e.g., 40.74224,-73.99386). The Intent parameter determines how the search is performed: checkin finds venues suitable for check-ins, global searches globally, browse searches within a specific area, and match attempts to match a specific venue. The endpoint uses a static URL (iteration.type: static.url) and does not require pagination. The response data path is $.response.venues[*], which extracts all items from the venues array in the API response. For detailed information about searching for venues, see the Foursquare Places API documentation.

    Get Venue Categories

    Returns a hierarchical list of categories applied to venues.

    • This endpoint automatically retrieves all venue categories from the Foursquare Places API. No additional configuration is required beyond selecting this endpoint template.
    • The endpoint uses GET requests to https://api.foursquare.com/v2/venues/categories?v=20200324&client_id={client_id}&client_secret={client_secret} where {client_id} is your Client ID from the credential configuration and {client_secret} is your Client Secret from the credential configuration. The endpoint URL is automatically constructed based on the Foursquare API base URL and the API version.
    • The endpoint does not use pagination and returns all venue categories in a single request.
    • The endpoint will return a hierarchical list of all venue categories. The response data is extracted from the categories array in the API response ($.response.categories[*]), with each category record processed individually.

    This endpoint returns the complete hierarchical category structure used by Foursquare to classify venues. Categories are organized in a tree structure with parent and child categories. The endpoint uses a static URL (iteration.type: static.url) and does not require pagination. The response data path is $.response.categories[*], which extracts all items from the categories array in the API response. For detailed information about venue categories, see the Foursquare Places API documentation.

    Details for Venues in Lookup

    Get venue details for venue IDs stored in a Nexla lookup table.

    • Select the Nexla lookup table that contains venue IDs from the Lookup for fetching Venue Ids dropdown menu. This lookup table should contain a column with venue IDs that you want to retrieve details for.

    • Enter the name of the column in the lookup table that contains the venue IDs in the Venue Id Column Name in Lookup field. This should match the exact column name in your lookup table.

    • The endpoint uses a two-step process: first, it iterates over the Nexla lookup to retrieve venue IDs, then it makes GET requests to https://api.foursquare.com/v2/venues/{venue_id}?v=20200324&client_id={client_id}&client_secret={client_secret} for each venue ID from the lookup. The endpoint URL is automatically constructed based on the Foursquare API base URL, the venue ID from the lookup, and the API version.
    • The endpoint does not use pagination and returns complete venue details for each venue ID in a single request per venue.
    • The endpoint will return detailed information for each venue ID found in the lookup table. The response data is extracted from the root-level object in the API response ($), and Nexla will process the entire response structure for each venue.

    This endpoint requires a Nexla lookup table containing venue IDs. The endpoint iterates over the lookup table and makes API requests for each venue ID found in the lookup. The Venue Id Column Name should match the exact column name in your lookup table. The endpoint uses a lookup iteration (iteration.type: data.map.key.queue) followed by a static URL (iteration.type: static.url) for each lookup entry. The response data path is $, which extracts the entire root-level object from the API response. For detailed information about getting venue details, see the Foursquare Places API documentation.

Endpoint Testing​

Once the selected endpoint template has been configured, Nexla can retrieve a sample of the data that will be fetched according to the current settings. This allows users to verify that the source is configured correctly before saving.

  • To test the current endpoint configuration, click the Test button to the right of the endpoint selection menu. Sample data will be fetched & displayed in the Endpoint Test Result panel on the right.

  • If the sample data is not as expected, review the selected endpoint and associated settings, and make any necessary adjustments. Then, click the Test button again, and check the sample data to ensure that the correct information is displayed.

Configure Manually​

Foursquare data sources can be manually configured to ingest data from any valid Foursquare Places API endpoint. Manual configuration provides maximum flexibility for accessing endpoints not covered by pre-built templates or when you need custom API configurations.

With manual configuration, you can also create more complex Foursquare sources, such as sources that use chained API calls to fetch data from multiple endpoints or sources that require custom authentication headers or request parameters.

API Method​

  1. To manually configure this source, select the Advanced tab at the top of the configuration screen.

  2. Select the API method that will be used for calls to the Foursquare Places API from the Method pulldown menu. The most common methods are:

    • GET: For retrieving data from the API
    • POST: For sending data to the API or triggering actions
    • PUT: For updating existing data
    • PATCH: For partial updates to existing data
    • DELETE: For removing data

API Endpoint URL​

  1. Enter the URL of the Foursquare Places API endpoint from which this source will fetch data in the Set API URL field. This should be the complete URL including the protocol (https://) and any required path parameters. Foursquare Places API endpoints typically follow the pattern https://api.foursquare.com/v2/{endpoint_path}?v=20200324&client_id={client_id}&client_secret={client_secret} where {client_id} and {client_secret} are your Client ID and Client Secret from the credential configuration.

Ensure the API endpoint URL is correct and accessible with your current credentials. You can test the endpoint using the Test button after configuring the URL. The endpoint requires Client ID and Client Secret authentication via query parameters (client_id and client_secret), which are handled automatically by your credential configuration. All Foursquare Places API requests must include the API version parameter (v=20200324). For detailed information about Foursquare Places API endpoints and available APIs, see the Foursquare Places API documentation.