BLIP Java SDK

A Java SDK for interacting with the Balihoo Local Information Platform (BLIP).

Requirements

• This SDK targets Java 7.
• Using this SDK requires that you already have API keys and are interacting on behalf of a brand that already exists in Balihoo's system. Please contact Balihoo if you require API keys and/or would like to add a new brand to our system.

Installation

The SDK is available to install from the Maven central repository.

Usage

    // Construct a Blip object
    Blip blip = new Blip("<Your API Key>", "<Your Secret Key>");
    
    // Make a method call and return the response
    BlipResponse brandResponse = blip.getBrandKeys();

    // Status Code (e.g. 200, 204, 404, etc.)
    int responseCode = brandResponse.STATUS_CODE;

    // Response Content
    String myBrands = brandResponse.BODY;

The Blip constructor has an optional "endpoint" parameter to specify the environment URL. The endpoint defaults to Balihoo's production environment but you can optionally pass the dev or stage URL.

Example

    // dev: https://blip.dev.balihoo-cloud.com
    // stage: https://blip.stage.balihoo-cloud.com
    // production: https://blip.balihoo-cloud.com
    Blip blip = new Blip("<Your API Key>", "<Your Secret Key>", "https://blip.dev.balihoo-cloud.com");

Methods

All methods return a BlipResponse object with two properties:

• STATUS_CODE
  • The HTTP response code (e.g. 200, 204, 404) as an integer.
• BODY
  • The HTTP response content as a string.
  • For calls that return brand or location data this property will contain stringified JSON objects.

ping

Ping the BLIP API.

Example

    Blip blip = new Blip("<Your API Key>", "<Your Secret Key>");
    BlipResponse blipResponse = blip.ping();

    if (blipResponse.STATUS_CODE == 200)
    {
      // Success!
    }

---

getBrandKeys

Get a list of brandKeys that the API user is authorized to access.

Example

    Blip blip = new Blip("<Your API Key>", "<Your Secret Key>");
    BlipResponse blipResponse = blip.getBrandKeys();

    String myBrandKeys = blipResponse.BODY;

---

getBrandSources

Get a list of data sources available for an individual brand.

Parameters

• brandKey: The unique identifier for a single brand.

Example

    Blip blip = new Blip("<Your API Key>", "<Your Secret Key>");
    BlipResponse blipResponse = blip.getBrandSources("mybrand");

    String sources = blipResponse.BODY;

---

getBrandProjections

Get a list of data projections available for an individual brand.

Parameters

• brandKey: The unique identifier for a single brand.

Example

    Blip blip = new Blip("<Your API Key>", "<Your Secret Key>");
    BlipResponse blipResponse = blip.getBrandProjections("mybrand");

    String projections = blipResponse.BODY;

---

getLocationKeys

Get a list of locationKeys for all locations belonging to the specified brand.

Parameters

• brandKey: The unique identifier for a single brand.
• projection: Optionally filter data in a single projection. Defaults to "universal".

Example

    Blip blip = new Blip("<Your API Key>", "<Your Secret Key>");
    BlipResponse blipResponse = blip.getLocationKeys("mybrand");

    String locationKeys = blipResponse.BODY;

---

getLocation

Get data for an individual location within the specified brand.

Parameters

• brandKey: The unique identifier for a single brand.
• locationKey: The unique identifier for a single location within the brand.
• projection: Optionally filter data in a single projection. Defaults to "universal".
• includeRefs: Optionally include objects referenced by the location in its data. Defaults to false.

Example

    Blip blip = new Blip("<Your API Key>", "<Your Secret Key>");
    BlipResponse blipResponse = blip.getLocation("mybrand", "mylocation");

    String locationData = blipResponse.BODY;

---

queryLocations

Get data for locations in a single brand filtered by the specified BLIP query.

Parameters

• brandKey: The unique identifier for a single brand.
• query: A stringified JSON query used to filter locations.
• view: Optionally specify the view returned. Defaults to "full".
• pageSize: Optionally specify the number of results to include in each page of results.
• pageNumber: Optionally specify the page index to return.
• sortColumn: Optionally sort results by "name" or "locationKey". Defaults to "locationKey".
• sortDirection: Optionally specify sorting "asc" or "desc". Defaults to "asc".

Example

    Blip blip = new Blip("<Your API Key>", "<Your Secret Key>");
    String query = "{\"address.state\":{\"equals\":\"ID\"}}";
    BlipResponse blipResponse = blip.queryLocations("mybrand", query);

    String matchingLocations = blipResponse.BODY;

---

putLocation

Add a new location or update an existing location's data.

Parameters

• brandKey: The unique identifier for a single brand.
• locationKey: The unique identifier for a single location within the brand.
• source: The name of the data source being used to add/update the location
• locationData: The stringified JSON location document.

Example

    Blip blip = new Blip("<Your API Key>", "<Your Secret Key>");
    String locationDocument = "{\"name\":\"Balihoo, Inc.\",\"address\":{\"city\":\"Boise\",\"state\":\"ID\"}}";
    BlipResponse blipResponse = blip.putLocation("mybrand", "mylocation", "mysource", locationDocument);

    if (blipResponse.STATUS_CODE == 204)
    {
        // location was successfully added/updated
    }

---

deleteLocation

Delete an individual location.

Parameters

• brandKey: The unique identifier for a single brand.
• locationKey: The unique identifier for a single location within the brand.
• source: The name of the data source being used to delete the location

Example

    Blip blip = new Blip("<Your API Key>", "<Your Secret Key>");
    BlipResponse blipResponse = blip.deleteLocation("mybrand", "mylocation", "mysource");

    if (blipResponse.STATUS_CODE == 204)
    {
        // location was successfully deleted
    }

---

bulkLoad

Load a single file containing multiple locations.

Parameters

• brandKey: The unique identifier for a single brand.
• source: The unique identifier for the data source being used to add/update the location.
• filePath: The full path to the bulk location file. See note below on the bulk load file format.
• implicitDelete: Whether or not to delete locations from BLIP if they're missing from the file.
• expectedRecordCount: The number of location records to expect in the file.
• successEmail: An optional email address to notify upon success. Can be a comma-delimited list.
• failEmail: An optional email address to notify upon failure. Can be a comma-delimited list.
• successCallbackUrl: An optional URL to call upon success.
• failCallbackUrl: An optional URL to call upon failure.

Example

    Blip blip = new Blip("<Your API Key>", "<Your Secret Key>");
    BlipResponse blipResponse = blip.bulkLoad("mybrand", "mysource", "/tmp/myfile.json", true, 50, 
                                              "[email protected]", "[email protected],[email protected]",
                                              "http://mycompany.com/api?success=true", "http://mycompany.com/api?error=true");

    if (blipResponse.STATUS_CODE == 204)
    {
        // File load has been successfully initiated.
        // Optional success and failure notifications will be made once the load process completes.
    }

Bulk Load File Format

The file for the bulkLoad process should contain each location's data on a single line and each line delimited by a line-feed character (\n). If a location is omitted from the file and implicitDelete is set to true, the location will be deleted.

Simplified Example

{"brandKey":"mybrand","locationKey":"ABC123","document":{...}}\n
{"brandKey":"mybrand","locationKey":"ABC124","document":{...}}\n
{"brandKey":"mybrand","locationKey":"ABC125","document":{...}}\n