API
Using the Grappos API

Overview

Download Demo Code
The Grappos API is available to Grappos customers and gives developers access to the data required to build custom product locator solutions.

The Grappos API returns data for products, retailers and locations. Outlined below you can find a brief description of each of the various calls that can be used to retrieve data.

The standard data flow is to use the Subscriber API to get the list of Products associated with your UID. This information can then be used in the Search API to find nearby retailers.

You can contact Grappos for Product IDs or use the names as displayed in your locator.

Note: If you provide your data to Grappos via an API, the Grappos API may not function as expected. Please contact us before you begin development to ensure compatibility.

 

Location API

The Location API can be used to obtain the latitude and longitude of various locations. The service allows you to get details by Postal Code (“94105”) or by City Name (“San Francisco”).

URL: http://www.grappos.com/api2/locate.php

Parameter Description
src Your Website domain
Used to identify source of API requests
locate Postal Code or City Name
ex: “94105”, “San Francisco”
format Format of the data to be returned.
Available Option: “json”
limit Maximum number of matching locations to return

Location Results will have the following JSON format.

{ "locations" : [
    { 
        "displayName": "San Francisco, CA 94104",
        "lat": "37.775000",
        "lon": "-122.418300",
        "zip": "94105" 
    },
    ....
] }

 

Subscriber API

The Subscriber API is used to obtain the list of Products associated with a Subscriber.

URL: https://www.grappos.com/etc/data-api/subscriber/products/

Parameter Description
src Your Website domain
Used to identify source of API requests
uid Subscriber Unique Identifier (“UID”)
format Format of the data to be returned.
Available Option: “json”

Subscriber Results will have the following JSON format.

{"products": [
    { 
        "ProductID" : "10890591", 
        "description" : "Archery Summit Arcus Estate Pinot Noir", 
        "BrandID" : "300", 
        "Brand" : "Archery Summit", 
        "is_toppick" : 0
    } ,
    ....
] }

 

Search API

The Search API can be used to search for Retailers that carry specific Products or Brands.

URL (data clients): https://www.grappos.com/etc/data-api/search/
 
URL (VIP API clients): https://www.grappos.com/etc/data-api/search/vip/
 
Note: If you are unsure which URL to use, please contact us.

Parameter Description
src Your Website domain
Used to identify source of API requests
lat Location Latitude to be searched
lon Location Longitude to be searched
product_id Product ID to be searched
brand_id Brand ID to be searched
store_type What Premises should be searched for?
Available Options: “Stores”, “Restaurants”, or “All Retailers”
format Format of the data to be returned.
Available Option: “json”
limit Maximum Retailers to Return

Retailer results will have the following JSON format.

{
    "retailers": [
        { 
            "RetailerID" : "61621",
            "name" : "Pastabilities",
            "addr1" : "311 S Franklin St ",
            "addr2" : "",
            "city" : "Syracuse",
            "state" : "New York",
            "state_abbr" : "New York",
            "zip" : "13202",
            "phone" : "",
            "lat" : "43.048633",
            "lon" : "-76.155551",
            "is_retail" : "0",
            "is_on_premise" : "1",
            "distance" : 8.54603127392469 
        } ,
        ...
    ]
}

Have Questions?

If you have questions about how to best configure your Grappos account locator or format your data, check out the FAQ or contact us and we’ll get back to you right away.