GET-ting Data from the API

Using the GET request you can query individual objects or lists of objects through the Buzz API. Buzz will automatically restrict you to objects in your Account and for which you have permission to read. In addition, only certain fields are query-able for a given object. GETs can be used in conjunction with Extras to allow more flexibility in requesting data.

Examples of GET requests

Examples of various parameters accepted for GET requests are shown below.

# Gets all Advertisers in the account (no selection criteria provided)
curl -X GET "[host]/rest/advertiser" -b cookies.txt 
	-d '{}'

# Gets all Advertisers in the account and outputs results in Excel format.
curl -X GET "[host]/rest/advertiser" -b cookies.txt 
	-d '{"format":"xls"}'

#Get the Advertiser with id=1
curl -X GET "[host]/rest/advertiser" -b cookies.txt 
	-d '{"advertiser_id":1}'

#Get the Advertiser with id=1 (alternative format)
curl -X GET "[host]/rest/advertiser/1" -b cookies.txt

#Get Advertisers with ids 1, 2, or 3. 
#Array syntax can be used to OR any of the search terms.
curl -X GET "[host]/rest/advertiser" -b cookies.txt 
	-d '{"advertiser_id":[1,2,3]}'

#Get any Advertiser with the name “advertiser” (exact match)
curl -X GET "[host]/rest/advertiser" -b cookies.txt 
	-d  '{"advertiser_name":"advertiser"}'

#Get any Advertiser with the word "advertiser" anywhere 
# in its name. Note, this is generally only available on _name fields.
curl -X GET "[host]/rest/advertiser" -b cookies.txt 
	-d '{"advertiser_name":"%advertiser%"}'

#Get any Advertiser that does not have the word "advertiser" in its name.
curl -X GET "[host]/rest/advertiser" -b cookies.txt 
	-d  '{"advertiser_name":"!%advertiser%"}'

# Get any Advertiser where the advertiser_id is not =1. Note, this is passed as a String even if the field is an int.
curl -X GET "[host]/rest/advertiser" -b cookies.txt 
	-d '{"advertiser_id":"!1"}

# Get any Advertiser where the advertiser_id is >1. Supported modifiers are "<", ">", ">=", and "<=". Note, this is passed as a String even if the field is an int.
curl -X GET "[host]/rest/advertiser" -b cookies.txt 
	-d '{"advertiser_id":">1"}

# Get any Advertiser where the advertiser_name is NULL
curl -X GET "[host]/rest/advertiser" -b cookies.txt 
	-d '{"advertiser_name":""}'

#Get any Advertiser where the advertiser_name is NULL (same as blank). Note, "NULL" is passed as a string, if you pass NULL the field is ignored

curl -X GET "[host]/rest/advertiser" -b cookies.txt 
	-d '{"advertiser_name":"NULL"}'

# Get any Advertiser where the advertiser_name is not NULL.
curl -X GET "[host]/rest/advertiser" -b cookies.txt 
	-d '{"advertiser_name":"!NULL"}'

# Get any Advertiser with the word “advertiser” in its name, that is also currently active. Note, you can also use boolean `true` or the string `"true"` to filter boolean fields.
curl -X GET "[host]/rest/advertiser" -b cookies.txt 
	-d '{"advertiser_name":"advertiser", "active":1}'

# Get any Advertiser with a create_date greater than Jan 1, 2015 AND less than Feb 1, 2015. The double-ampersand "&&" characters separate AND queries for a single field, allowing for ranges. See [Date Filtering](doc:date-filtering).

curl -X GET "[host]/rest/advertiser" -b cookies.txt 
	-d '{"create_date":">2015-01-01&&<2015-02-01"}'

# Get any Advertiser that was created today. Date fields can be filtered using a number of "magic" strings. See: [Date Filtering](doc:date-filtering).

curl -X GET "[host]/rest/advertiser" -b cookies.txt 
	-d '{"create_date":"today"}'

# Use the "advertiser_view" View to format the response.
curl -X GET "[host]/rest/advertiser" -b cookies.txt 
	-d '{"advertiser_name":"advertiser", "active":1, "view_name":"advertiser_view"}'

# Apply query modifiers to the list returned from the API. Described more below...

curl -X GET "[host]/rest/advertiser" -b cookies.txt 
	-d '{"advertiser_name":"advertiser", "active":1,”rows":2,"offset":1,
  "sort_by":["advertiser_id","advertiser_name"],"order":"desc"}'

Special Query Parameters for GETs

GET requests support four special query parameters that allow you to paginate and sort the results. These parameters are always optional.

GET Parameter	Usage	Default
`rows`	Number of rows to return. Max is 3000. This value can be configured by Beeswax support.	50
`offset`	Offset from the query results to deliver to the API request. E.g. if there are 55 results and the offset is 5, the API will return rows 5-55.	0
`sort_by`	The fields to sort by. Only searchable fields can be used to sort. Accepts multiple fields in a list `"sort_by":["field1","field2"]`	The first field, typically the unique ID of the object
`order`	The order to sort by. `0` = ascending (default), `1` or `DESC` for descending order. To sort multiple fields in multiple orders use a list: `"order":[0,1,0]` where each entry corresponds to the field in the `sort_by` parameter.	Ascending or `0`
`view_name`	An alternative view to use for querying the object, see below for more detail	None

Views

The fields returned from a GET request can be determined by "Views". Views have no effect on PUTs, DELETEs, or POSTs. A single object can have multiple Views with one set as the default.

To see the views and fields associated with an object use the views extra.

The GET responses behavior will be as follows:

GET request parameters	Result
No view specified	Return all fields in the object
`"view_name":"foobar"`	Use the `foobar` view to format the results. If foobar does not exist or is associated with another object an error will be thrown.
`"view_name":"none"`	Same as no view specified

There is also a View endpoint that can be used for static lookup data, like a list of all available browsers or operating systems for targeting.

Fields

In addition to selecting a View for determining the output of your GET request, you can also specify specific fields by using the fields list in the request. The field names specified will be the only ones selected and the field order will be the order specified.

When using the fields parameter the following fields will be included in the response even when not specified: account_id, buzz_key, active, and the object's primary key.

curl -X GET "[host]/rest/advertiser" -b cookies.txt 
	-d '{"advertiser_name":"advertiser", "active":1, "fields":["advertiser_id","advertiser_name"]}'