RESTful API Access
GSAPI uses the token and signature method for authentication across HTTPS protocol. This allows for top security of data and also provides the ability for customization on a per token basis. Certainly we will find out in no time just how many customizations are possible.
API URL Structure
There is a standard URL structure for all API accesses. The structure is as follows and must always be accessed via HTTPS protocol.
All URLs (end points) must include https://grandstrandapi.com/api/v1/component/
This is followed by the ID or the Method/ID depending on the circumstances. For example,
https://grandstrandapi.com/api/v1/component/id/
https://grandstrandapi.com/api/v1/component/method/id/
Each of these routes are considered the endpoints as far as the GSAPI is concerned. Other request parameters are available and can be used depending on the component endpoint accessed. These additional parameters follow the URL just like any other web query. For possible parameters see each component below.
Endpoint Components
Several components are available for easy query. This will assist you in developing versatile applications and websites. While sticking with the big data methodology, we have tried to keep things simple and to the point to adhere to the needs of most developers.
Components are the main section of the API that is being accessed. Current components include: category, places, search and events.
Category Component
The category component will query the information about a certain category and all of it’s subcategories. This is useful for compiling the menus and navigation of your application. The following are examples of some typical queries.
https://grandstrandapi.com/api/v1/category/1/
Returns the base “Home” category in JSON format along with the main categories just below it. (FIG A)
https://grandstrandapi.com/api/v1/category/845/
Does the same for specific categories within the category structure. In this case it’s Hotels & Lodging with a category ID of 845. (FIG B)
Due to the simplicity of the category component and it’s intended usage, it receives no parameters. All will be ignored.
Places Component
The places component queries the actual results within a category depending on various parameters passed. By default the sort order uses our points matrix which calculates ranking, votes and other review criteria. In the end the result looks pretty close to sort by ranking.
https://grandstrandapi.com/api/v1/places/851/
Returns the default results of the places component. In the case here category with ID 851 is displayed with a default items per page of 20. (FIG C)
Parameters:
lat / lng: Latitude and longitude must be used together to trigger the radius system. Engages and returns the distance variable as seen here (FIG D) sorting by distance by default closest first.
rad: The radius parameter sets the distance in radius to base results on. Defaults to 10 miles from set lat/lng.
st: Start records at nn. This will begin the results starting with record nn and will produce 20 records from that point.
pp: Sets the number of records per page. Defaults to 20.
pop: Toggle the pop parameter with pop=1 to display the highest ranked items within the radius first overriding the sort by distance. This makes creating ‘sort by distance’ and ‘sort by popularity’ buttons a breeze.
https://grandstrandapi.com/api/v1/places/detail/2193
The detail method of the places component returns the full data available on a given place. Use the detail method to build your individual places pages when the title or ‘read more’ is selected.
Some developers like a robust page and some a more streamlined page. We created to the des parameter below so that everybody is happy. Without des=1 the record will just return null as shown. (FIG E)
Parameters:
des: The des parameter toggles the description information to ON using des=1 (defaults to 0). Claimed listings allow the customer to add a good portion of text about their place. In your development you may not have a need for all this extra information; most people won’t. Turning des ON in your parameters will return the description as well the other place information.
med: The med parameter is a three position toggle with a default of 0 to conserve data transfer and improve app speed no images will be returned. med=1 returns an image[primary], recommended image[icon]. med=2 returns everything in 1 and additionally returns up to 4 images image[2-5]. The image limit for listings is 5 and are listing owner approved. These are not web user contributed keeping quality to it’s best.
Search Component
The search component searches for listings with the search term query within the name or listings tagged with the search term.
By default the sort order uses our points matrix which calculates ranking, votes and other review criteria. In the end the result looks pretty close to sort by ranking.
https://grandstrandapi.com/api/v1/search/places?q=TERM
Searches the businesses for all businesses with a name similar to “TERM”. Please note search terms must be 4 characters or longer
Parameters:
lat / lng: Latitude and longitude must be used together to trigger the radius system. Engages and returns the distance variable as seen here (FIG D) sorting by distance by default closest first.
rad: The radius parameter sets the distance in radius to base results on. Defaults to 10 miles from set lat/lng.
st: Start records at nn. This will begin the results starting with record nn and will produce 20 records from that point.
pp: Sets the number of records per page. Defaults to 20.
pop: Toggle the pop parameter with pop=1 to display the highest ranked items within the radius first overriding the sort by distance. This makes creating ‘sort by distance’ and ‘sort by popularity’ buttons a breeze.
med: The med parameter is a two position toggle with a default of 0 to conserve data transfer and improve app speed no images will be returned. med=1 returns an image[primary]. These are not web user contributed keeping quality to it’s best.
Places Sorted by Rating
Places Distance from Radius
Value Added Endpoints
Weather in Myrtle Beach
https://grandstrandapi.com/api/v1/weather/current/
https://grandstrandapi.com/api/v1/weather/fiveday/
Lowest Gas Prices Within 10 Mile Radius
https://grandstrandapi.com/api/v1/gasprices/
