{"_id":"56cf4c4c287eb20b009f9f01","project":"56c35c56c0c4630d004e864c","user":"56c39c05bc41330d009f25d7","__v":7,"category":{"_id":"56c35c57c0c4630d004e8650","version":"56c35c56c0c4630d004e864f","__v":17,"pages":["56c35c58c0c4630d004e8652","56c38f9c2d97560d00e23cb8","56c39b11e1e4190d003429b0","56c3a90c28bd680d005e7aa3","56c7b98a8bf67e0d0073477a","56c7b9d7379b311700ed8fe1","56c7bcc55652c217008e0923","56c7bee8606ee717003c4769","56cf423f8629f91300fd9779","56cf45b944c5700b0095c175","56cf4709287eb20b009f9eec","56cf49208acacb1300814884","56cf4c4c287eb20b009f9f01","56cf4d968629f91300fd9797","56cf4ede8acacb1300814890","56cf520b8629f91300fd97a9","56cf52d5287eb20b009f9f12"],"project":"56c35c56c0c4630d004e864c","sync":{"url":"","isSync":false},"reference":true,"createdAt":"2016-02-16T17:28:55.483Z","from_sync":false,"order":0,"slug":"documentation","title":"Buzz API Overview"},"githubsync":"","version":{"_id":"56c35c56c0c4630d004e864f","project":"56c35c56c0c4630d004e864c","__v":8,"createdAt":"2016-02-16T17:28:54.864Z","releaseDate":"2016-02-16T17:28:54.864Z","categories":["56c35c57c0c4630d004e8650","56c7b9e5379b311700ed8fe3","56c7bab4606ee717003c4766","56c7bb3613e5400d001e8cbd","56cf3f5a5267d70b00494c4b","56cf3f866c5d7a13005ee894","56fd3956caad892200847bce","599da256e7742b002588bb02"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"0.5.0","version":"0.5"},"parentDoc":null,"updates":["58701f34b27e160f00820b4a","59ca582d8fde450010660678"],"next":{"pages":[],"description":""},"createdAt":"2016-02-25T18:47:40.824Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[]},"method":"get","results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":true,"order":3,"body":"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.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Examples of GET requests\"\n}\n[/block]\nGets all Advertisers in the account (no selection criteria provided)\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X GET \\\"[host]/rest/advertiser\\\" -b cookies.txt -d '{}'\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\nGets all Advertisers in the account and outputs results in Excel format. See [Converting GET Requests into Other Formats](doc:converting-get-requests-into-other-formats) .\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X GET \\\"[host]/rest/advertiser\\\" -b cookies.txt -d '{\\\"format\\\":\\\"xls\\\"}'\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\nGet the Advertiser with id=1\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X GET \\\"[host]/rest/advertiser\\\" -b cookies.txt -d '{\\\"advertiser_id\\\":1}'\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\nGet the Advertiser with id=1 (alternative format)\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X GET \\\"[host]/rest/advertiser/1\\\" -b cookies.txt\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\nGet Advertisers with ids 1, 2, or 3. Array syntax can be used to OR any of the search terms.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X GET \\\"[host]/rest/advertiser\\\" -b cookies.txt -d '{\\\"advertiser_id\\\":[1,2,3]}'\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\nGet any Advertiser with the name “advertiser” (exact match)\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X GET \\\"[host]/rest/advertiser\\\" -b cookies.txt -d  '{\\\"advertiser_name\\\":\\\"advertiser\\\"}'\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\nGet any Advertiser with the word \"advertiser\" anywhere in its name. Note, this is generally only \navailable on `_name` fields.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X GET \\\"[host]/rest/advertiser\\\" -b cookies.txt -d '{\\\"advertiser_name\\\":\\\"%advertiser%\\\"}'\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\nGet any Advertiser that does not have the word \"advertiser\" in its name.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X GET \\\"[host]/rest/advertiser\\\" -b cookies.txt -d  '{\\\"advertiser_name\\\":\\\"!%advertiser%\\\"}'\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\nGet any Advertiser where the advertiser_id is not =1. Note, this is passed as a String even if the field is an int.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X GET \\\"[host]/rest/advertiser\\\" -b cookies.txt -d '{\\\"advertiser_id\\\":\\\"!1\\\"}\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\nGet 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.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \" curl -X GET \\\"[host]/rest/advertiser\\\" -b cookies.txt -d '{\\\"advertiser_id\\\":\\\">1\\\"}\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\nGet any Advertiser where the advertiser_name is NULL\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X GET \\\"[host]/rest/advertiser\\\" -b cookies.txt -d '{\\\"advertiser_name\\\":\\\"\\\"}'\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\nGet 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\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X GET \\\"[host]/rest/advertiser\\\" -b cookies.txt -d '{\\\"advertiser_name\\\":\\\"NULL\\\"}'\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\nGet any Advertiser where the advertiser_name is not NULL.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X GET \\\"[host]/rest/advertiser\\\" -b cookies.txt -d '{\\\"advertiser_name\\\":\\\"!NULL\\\"}'\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\nGet 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.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X GET \\\"[host]/rest/advertiser\\\" -b cookies.txt -d '{\\\"advertiser_name\\\":\\\"advertiser\\\", \\\"active\\\":1}'\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\nGet 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).\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X GET \\\"[host]/rest/advertiser\\\" -b cookies.txt -d '{\\\"create_date\\\":\\\">2015-01-01&&<2015-02-01\\\"}'\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\nGet any Advertiser that was created today. Date fields can be filtered using a number of \"magic\" strings. See: [Date Filtering](doc:date-filtering).\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X GET \\\"[host]/rest/advertiser\\\" -b cookies.txt -d '{\\\"create_date\\\":\\\"today\\\"}'\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\nUse the \"advertiser_view\" View to format the response.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X GET \\\"[host]/rest/advertiser\\\" -b cookies.txt -d '{\\\"advertiser_name\\\":\\\"advertiser\\\", \\\"active\\\":1, \\\"view_name\\\":\\\"advertiser_view\\\"}'\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\nApply query modifiers to the list returned from the API. Described more below...\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X GET \\\"[host]/rest/advertiser\\\" -b cookies.txt -d\\n  '{\\\"advertiser_name\\\":\\\"advertiser\\\", \\\"active\\\":1,”rows\\\":2,\\\"offset\\\":1,\\n  \\\"sort_by\\\":[\\\"advertiser_id\\\",\\\"advertiser_name\\\"],\\\"order\\\":\\\"desc\\\"}'\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"get\",\n  \"title\": \"Special Query Parameters for GETs\"\n}\n[/block]\nGET requests support four special query parameters that allow you to paginate and sort the results. These parameters are always optional.\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"GET Parameter\",\n    \"h-1\": \"Usage\",\n    \"h-2\": \"Default\",\n    \"0-0\": \"`rows`\",\n    \"0-1\": \"Number of rows to return.  Max is 2500.\",\n    \"0-2\": \"50\",\n    \"1-0\": \"`offset`\",\n    \"1-1\": \"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.\",\n    \"1-2\": \"0\",\n    \"2-0\": \"`sort_by`\",\n    \"2-1\": \"The fields to sort by. Only searchable fields can be used to sort. Accepts multiple fields in a list `\\\"sort_by\\\":[\\\"field1\\\",\\\"field2\\\"]`\",\n    \"2-2\": \"The first field, typically the unique ID of the object\",\n    \"3-0\": \"`order`\",\n    \"3-1\": \"The order to sort by. `0` = ascending (default), `1` or  `DESC` for descending order. \\n\\nTo 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.\",\n    \"3-2\": \"Ascending or `0`\",\n    \"4-0\": \"`view_name`\",\n    \"4-1\": \"An alternative view to use for querying the object, see below for more detail\",\n    \"4-2\": \"None\"\n  },\n  \"cols\": 3,\n  \"rows\": 5\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"get\",\n  \"title\": \"Views\"\n}\n[/block]\nThe fields returned from a GET request are determined by \"Views\" defined by the Buzz administrator. Views have no effect on PUTs, DELETEs, or POSTs. A single object can have multiple Views with one set as the default.\n\nThe GET responses behavior will be as follows:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"GET request parameters\",\n    \"h-1\": \"Result\",\n    \"0-0\": \"No view specified\",\n    \"0-1\": \"Return all fields in the object\",\n    \"1-0\": \"`\\\"view_name\\\":\\\"foobar\\\"`\",\n    \"1-1\": \"Use the \\\"foobar\\\" view to format the results. If foobar does not exist or is associated with another object an error will be thrown.\",\n    \"2-0\": \"`\\\"view_name\\\":\\\"none\\\"`\",\n    \"2-1\": \"Same as no view specified\"\n  },\n  \"cols\": 2,\n  \"rows\": 3\n}\n[/block]\nA View is based on a SQL View and can include joints, sums, counts, etc. Views thus allow you to see related information from other tables, or do other manipulation in the database to save time in the API. To see the views and fields associated with an object use the `views` extra.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Fields\"\n}\n[/block]\nIn 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 (other than some system fields) and the field order will be the order specified. To get all fields \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X GET \\\"[host]/rest/advertiser\\\" -b cookies.txt -d '{\\\"advertiser_name\\\":\\\"advertiser\\\", \\\"active\\\":1, \\\"fields\\\":[\\\"advertiser_id\\\",\\\"advertiser_name\\\"]}'\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]","excerpt":"","slug":"get-ting-data-from-the-api","type":"endpoint","title":"GET-ting Data from the API"}

getGET-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. [block:api-header] { "type": "basic", "title": "Examples of GET requests" } [/block] Gets all Advertisers in the account (no selection criteria provided) [block:code] { "codes": [ { "code": "curl -X GET \"[host]/rest/advertiser\" -b cookies.txt -d '{}'", "language": "curl" } ] } [/block] Gets all Advertisers in the account and outputs results in Excel format. See [Converting GET Requests into Other Formats](doc:converting-get-requests-into-other-formats) . [block:code] { "codes": [ { "code": "curl -X GET \"[host]/rest/advertiser\" -b cookies.txt -d '{\"format\":\"xls\"}'", "language": "curl" } ] } [/block] Get the Advertiser with id=1 [block:code] { "codes": [ { "code": "curl -X GET \"[host]/rest/advertiser\" -b cookies.txt -d '{\"advertiser_id\":1}'", "language": "curl" } ] } [/block] Get the Advertiser with id=1 (alternative format) [block:code] { "codes": [ { "code": "curl -X GET \"[host]/rest/advertiser/1\" -b cookies.txt", "language": "curl" } ] } [/block] Get Advertisers with ids 1, 2, or 3. Array syntax can be used to OR any of the search terms. [block:code] { "codes": [ { "code": "curl -X GET \"[host]/rest/advertiser\" -b cookies.txt -d '{\"advertiser_id\":[1,2,3]}'", "language": "curl" } ] } [/block] Get any Advertiser with the name “advertiser” (exact match) [block:code] { "codes": [ { "code": "curl -X GET \"[host]/rest/advertiser\" -b cookies.txt -d '{\"advertiser_name\":\"advertiser\"}'", "language": "curl" } ] } [/block] Get any Advertiser with the word "advertiser" anywhere in its name. Note, this is generally only available on `_name` fields. [block:code] { "codes": [ { "code": "curl -X GET \"[host]/rest/advertiser\" -b cookies.txt -d '{\"advertiser_name\":\"%advertiser%\"}'", "language": "curl" } ] } [/block] Get any Advertiser that does not have the word "advertiser" in its name. [block:code] { "codes": [ { "code": "curl -X GET \"[host]/rest/advertiser\" -b cookies.txt -d '{\"advertiser_name\":\"!%advertiser%\"}'", "language": "curl" } ] } [/block] Get any Advertiser where the advertiser_id is not =1. Note, this is passed as a String even if the field is an int. [block:code] { "codes": [ { "code": "curl -X GET \"[host]/rest/advertiser\" -b cookies.txt -d '{\"advertiser_id\":\"!1\"}", "language": "curl" } ] } [/block] 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. [block:code] { "codes": [ { "code": " curl -X GET \"[host]/rest/advertiser\" -b cookies.txt -d '{\"advertiser_id\":\">1\"}", "language": "curl" } ] } [/block] Get any Advertiser where the advertiser_name is NULL [block:code] { "codes": [ { "code": "curl -X GET \"[host]/rest/advertiser\" -b cookies.txt -d '{\"advertiser_name\":\"\"}'", "language": "curl" } ] } [/block] 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 [block:code] { "codes": [ { "code": "curl -X GET \"[host]/rest/advertiser\" -b cookies.txt -d '{\"advertiser_name\":\"NULL\"}'", "language": "curl" } ] } [/block] Get any Advertiser where the advertiser_name is not NULL. [block:code] { "codes": [ { "code": "curl -X GET \"[host]/rest/advertiser\" -b cookies.txt -d '{\"advertiser_name\":\"!NULL\"}'", "language": "curl" } ] } [/block] 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. [block:code] { "codes": [ { "code": "curl -X GET \"[host]/rest/advertiser\" -b cookies.txt -d '{\"advertiser_name\":\"advertiser\", \"active\":1}'", "language": "curl" } ] } [/block] 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). [block:code] { "codes": [ { "code": "curl -X GET \"[host]/rest/advertiser\" -b cookies.txt -d '{\"create_date\":\">2015-01-01&&<2015-02-01\"}'", "language": "curl" } ] } [/block] Get any Advertiser that was created today. Date fields can be filtered using a number of "magic" strings. See: [Date Filtering](doc:date-filtering). [block:code] { "codes": [ { "code": "curl -X GET \"[host]/rest/advertiser\" -b cookies.txt -d '{\"create_date\":\"today\"}'", "language": "curl" } ] } [/block] Use the "advertiser_view" View to format the response. [block:code] { "codes": [ { "code": "curl -X GET \"[host]/rest/advertiser\" -b cookies.txt -d '{\"advertiser_name\":\"advertiser\", \"active\":1, \"view_name\":\"advertiser_view\"}'", "language": "curl" } ] } [/block] Apply query modifiers to the list returned from the API. Described more below... [block:code] { "codes": [ { "code": "curl -X GET \"[host]/rest/advertiser\" -b cookies.txt -d\n '{\"advertiser_name\":\"advertiser\", \"active\":1,”rows\":2,\"offset\":1,\n \"sort_by\":[\"advertiser_id\",\"advertiser_name\"],\"order\":\"desc\"}'", "language": "curl" } ] } [/block] [block:api-header] { "type": "get", "title": "Special Query Parameters for GETs" } [/block] GET requests support four special query parameters that allow you to paginate and sort the results. These parameters are always optional. [block:parameters] { "data": { "h-0": "GET Parameter", "h-1": "Usage", "h-2": "Default", "0-0": "`rows`", "0-1": "Number of rows to return. Max is 2500.", "0-2": "50", "1-0": "`offset`", "1-1": "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.", "1-2": "0", "2-0": "`sort_by`", "2-1": "The fields to sort by. Only searchable fields can be used to sort. Accepts multiple fields in a list `\"sort_by\":[\"field1\",\"field2\"]`", "2-2": "The first field, typically the unique ID of the object", "3-0": "`order`", "3-1": "The order to sort by. `0` = ascending (default), `1` or `DESC` for descending order. \n\nTo 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.", "3-2": "Ascending or `0`", "4-0": "`view_name`", "4-1": "An alternative view to use for querying the object, see below for more detail", "4-2": "None" }, "cols": 3, "rows": 5 } [/block] [block:api-header] { "type": "get", "title": "Views" } [/block] The fields returned from a GET request are determined by "Views" defined by the Buzz administrator. Views have no effect on PUTs, DELETEs, or POSTs. A single object can have multiple Views with one set as the default. The GET responses behavior will be as follows: [block:parameters] { "data": { "h-0": "GET request parameters", "h-1": "Result", "0-0": "No view specified", "0-1": "Return all fields in the object", "1-0": "`\"view_name\":\"foobar\"`", "1-1": "Use the \"foobar\" view to format the results. If foobar does not exist or is associated with another object an error will be thrown.", "2-0": "`\"view_name\":\"none\"`", "2-1": "Same as no view specified" }, "cols": 2, "rows": 3 } [/block] A View is based on a SQL View and can include joints, sums, counts, etc. Views thus allow you to see related information from other tables, or do other manipulation in the database to save time in the API. To see the views and fields associated with an object use the `views` extra. [block:api-header] { "type": "basic", "title": "Fields" } [/block] 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 (other than some system fields) and the field order will be the order specified. To get all fields [block:code] { "codes": [ { "code": "curl -X GET \"[host]/rest/advertiser\" -b cookies.txt -d '{\"advertiser_name\":\"advertiser\", \"active\":1, \"fields\":[\"advertiser_id\",\"advertiser_name\"]}'", "language": "text" } ] } [/block]