API
Using the Grappos API

Overview

The Grappos API allows developers access to the data required to build custom product locator solutions. The API is available to all Grappos customers at no additional cost.

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.

Contact Grappos for Product IDs or use the names as displayed in your locator.

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 (“94103”) or City Name (“San Francisco, CA”).

URL: https://api.grappos.com/api/search/

Parameter Description
q Postal Code (e.g.: “94103”)
City Name (e.g.: “San Francisco, CA”)

Location Results will have the following JSON format.

[
    { 
        "place_name": "San Francisco",
        "state": "CA",
        "lat": "37.775000",
        "lon": "-122.418300",
    },
]

 

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", 
    } ,
    ....
] }

 

Search API

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

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

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" : "NY",
            "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 locator, check out the FAQ or contact us and we’ll get back to you right away.