{"_id":"5537e1563faac70d00ff6da6","project":"542ac32254d88d140075fc36","__v":20,"user":"542ac2d054d88d140075fc29","category":{"_id":"542ac32254d88d140075fc3a","__v":7,"pages":["542ac32254d88d140075fc3c","55369f1f6fd3c40d00334978","5537e1563faac70d00ff6da6","5537e1f63e785d0d00be3feb","5537e22249a5800d00a28e54","5537e24b3faac70d00ff6da8","5537e26349a5800d00a28e56"],"project":"542ac32254d88d140075fc36","version":"542ac32254d88d140075fc39","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2014-09-30T14:50:10.530Z","from_sync":false,"order":0,"slug":"documentation","title":"Documentation"},"version":{"_id":"542ac32254d88d140075fc39","__v":4,"project":"542ac32254d88d140075fc36","createdAt":"2014-09-30T14:50:10.500Z","releaseDate":"2014-09-30T14:50:10.500Z","categories":["542ac32254d88d140075fc3a","542af0fd54d88d140075ff1b","542af128cedcfc140004b8d0","5537e2870899730d0081368d"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-04-22T17:58:46.206Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":4,"body":"[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"GET /dataset/:dataset\"\n}\n[/block]\n\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"parameter\",\n    \"h-1\": \"value\",\n    \"0-0\": \"key\",\n    \"0-1\": \"The API key associated with your account\",\n    \"1-0\": \"_limit\",\n    \"1-1\": \"Number of rows to return\",\n    \"2-0\": \"_remove\",\n    \"2-1\": \"Remove these columns from each row\",\n    \"4-0\": \"[column_name]\",\n    \"4-1\": \"Will return only rows where the value of this column matches\",\n    \"3-0\": \"_page\",\n    \"3-1\": \"Get more results by paginating them with a limit and a page parameter\"\n  },\n  \"cols\": 2,\n  \"rows\": 5\n}\n[/block]\n**Example Requests**\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"import requests\\n\\nr = requests.get(\\\"https://www.exversion.com/api/v1/dataset/[DATASET ID]?key=[YOUR API KEY]&_limit=100\\\")\",\n      \"language\": \"python\"\n    },\n    {\n      \"code\": \"<?php\\n\\t$ch = curl_init('https://www.exversion.com/api/v1/dataset/[DATASET ID]?key=[YOUR API KEY]&_limit=100');\\ncurl_setopt($ch, CURLOPT_RETURNTRANSFER, true);\\n$result = json_decode(curl_exec($ch));\\n?>\",\n      \"language\": \"php\"\n    },\n    {\n      \"code\": \"require 'unirest'\\nresponse = Unirest.get \\\"https://www.exversion.com/api/v1/dataset/[DATASET ID]?key=[YOUR API KEY]&_limit=100\\\"\",\n      \"language\": \"ruby\"\n    }\n  ]\n}\n[/block]\n**Example Response**\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\\"status\\\":200,\\n \\\"message\\\":\\\"Success\\\",\\n \\\"body\\\":[\\n  \\t{\\n  \\t\\t\\\"_id\\\":\\\"FSBEQAKJQJH059881.299319683364711375720224963\\\",\\n  \\t\\t\\\"lobbyist_first_name\\\":\\\"James\\\",\\n  \\t\\t\\\"lobbyist_last_name\\\":\\\"Connolly\\\",\\n  \\t\\t\\\"filing_year\\\":\\\"2012\\\"\\n\\t\\t},\\n\\t\\t{\\n    \\t\\\"_id\\\":\\\"FSBEQAKJQJH059857.653845592045361375720225585\\\",\\n    \\t\\\"lobbyist_first_name\\\":\\\"James\\\",\\n    \\t\\\"lobbyist_last_name\\\":\\\"Gilliam\\\",\\n    \\t\\\"filing_year\\\":\\\"2012\\\"\\n  \\t},\\n\\t\\t{\\n  \\t\\t\\\"_id\\\":\\\"FSBEQAKJQJH05984.6746827350097781375720228202\\\",\\n  \\t\\t\\\"lobbyist_first_name\\\":\\\"James\\\",\\n  \\t\\t\\\"lobbyist_last_name\\\":\\\"Alexander\\\",\\n  \\t\\t\\\"filing_year\\\":\\\"2012\\\"\\n\\t\\t},\\n\\t\\t{\\n \\t\\t\\t\\\"_id\\\":\\\"FSBEQAKJQJH059878.41251410109141375720234876\\\",\\n  \\t\\t\\\"lobbyist_first_name\\\":\\\"James\\\",\\n  \\t\\t\\\"lobbyist_last_name\\\":\\\"Banks\\\",\\n  \\t\\t\\\"filing_year\\\":\\\"2012\\\"\\n\\t\\t},\\n\\t\\t{\\n  \\t\\t\\\"_id\\\":\\\"FSBEQAKJQJH059890.543216294539121375720235255\\\",\\n  \\t\\t\\\"lobbyist_first_name\\\":\\\"James\\\",\\n  \\t\\t\\\"lobbyist_last_name\\\":\\\"Darnell\\\",\\n  \\t\\t\\\"filing_year\\\":\\\"2012\\\"\\n\\t\\t},\\n\\t\\t{\\n    \\t\\\"_id\\\":\\\"FSBEQAKJQJH059884.74339911080541375720244224\\\",\\n    \\t\\\"lobbyist_first_name\\\":\\\"James\\\",\\n    \\t\\\"lobbyist_last_name\\\":\\\"Henn\\\",\\n    \\t\\\"filing_year\\\":\\\"2012\\\"\\n  \\t},\\n\\t]\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Returning a Range of Values\"\n}\n[/block]\nYou can return all data that fits within a numerical range by submitting a max and min value within square brackets\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"https://exversion.com/api/v1/dataset/[DATASET ID]?key=xxx&age=[30:35]\",\n      \"language\": \"html\"\n    }\n  ]\n}\n[/block]\nTo return only values that are greater than or only those that are less than a certain number, just leave off one end of the range in your query\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"https://exversion.com/api/v1/dataset/[DATASET ID]?key=xxx&age=[:35]\",\n      \"language\": \"html\"\n    }\n  ]\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"https://exversion.com/api/v1/dataset/[DATASET ID]?key=xxx&age=[30:]\",\n      \"language\": \"html\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"danger\",\n  \"title\": \"Strings Are Not Numbers!\",\n  \"body\": \"Range queries only work on columns that have **numerical **data. It's very easy to accidentally load data into Exversion where numbers have been converted to strings. In some cases it may even be preferable (example: coordinates tend to do better stored as strings), but nevertheless these columns cannot be queried using ranges.\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Querying Inside a Column\"\n}\n[/block]\nExversion does not require an exact, case sensitive match. Filtering a column by \"NY\" will return all the rows where the value in that column is \"NY\" as well as rows where it is \"Brooklyn, NY\" or \"New York, NY\"\n\nHowever, some data on Exversion is multidimensional. A good example of this are datasets that contain columns with GeoJSON data in them. In these cases you can actually query within the column by switching from GET to POST\n\n**Example Requests**\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"import requests\\nimport json\\n\\nurl = 'https://www.exversion.com/api/v1/dataset/'\\npayload = {\\\"key\\\":[YOUR API KEY],\\\"query\\\":[{\\\"dataset\\\":[DATASET ID], \\\"params\\\":{\\\"properties.CNTRY_NAME\\\":\\\"Aruba\\\"}}]}\\nr = requests.post(url, data=json.dumps(payload))\",\n      \"language\": \"python\"\n    },\n    {\n      \"code\": \"<?php\\n\\t$post = json_encode(\\n    array('key'=>[YOUR API KEY],\\n          'query'=>array(\\n            array('dataset'=>[DATASET ID],\\n                  'params'=>array(\\n                    'properties.CNTRY_NAME'=>\\\"Aruba\\\")\\n                 )\\n          )\\n         )\\n  );\\n\\t\\t\\n\\t$ch = curl_init('https://www.exversion.com/api/v1/dataset/');\\ncurl_setopt($ch, CURLOPT_CUSTOMREQUEST, \\\"POST\\\");\\ncurl_setopt($ch, CURLOPT_POSTFIELDS, $post);\\ncurl_setopt($ch, CURLOPT_RETURNTRANSFER, true);\\ncurl_setopt($ch, CURLOPT_HTTPHEADER, array(\\n  'Content-Type: application/json',\\n  'Content-Length: ' . strlen($post))\\n           );\\n$result = json_decode(curl_exec($ch));\\n?>\",\n      \"language\": \"php\"\n    },\n    {\n      \"code\": \"require 'unirest'\\nresponse = Unirest.post \\\"https://www.exversion.com/api/v1/dataset/\\\", \\n\\t\\theaders:{ \\\"Accept\\\" => \\\"application/json\\\" }, \\n    parameters:{'key'=>[YOUR API KEY],\\n          'query'=>[{'dataset'=>[DATASET ID],\\n            'params'=>{'properties.CNTRY_NAME'=>\\\"Aruba\\\"}]}\",\n      \"language\": \"ruby\"\n    }\n  ]\n}\n[/block]\nThis will return any row where the JSON dict in column properties has a attribute named CNTRY_NAME with a value of Aruba \n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Remove Columns From Results\"\n}\n[/block]\nSome datasets might include more data than you really need. To remove unnecessary columns from the results returned, pass the column names as a comma separated list (no spaces). Note that this only removes the columns from your results, to remove them permanently from the dataset update the schema.\n\n**Example Requests**\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"import requests\\n\\nr = requests.get(\\\"https://www.exversion.com/api/v1/dataset/[DATASET ID]?key=[YOUR API KEY]&_remove=lobbyist_first_name,filing_year\\\")\",\n      \"language\": \"python\"\n    },\n    {\n      \"code\": \"<?php\\n\\t$ch = curl_init('https://www.exversion.com/api/v1/dataset/[DATASET ID]?key=[YOUR API KEY]&_remove=lobbyist_first_name,filing_year');\\ncurl_setopt($ch, CURLOPT_RETURNTRANSFER, true);\\n$result = json_decode(curl_exec($ch));\\n?>\",\n      \"language\": \"php\"\n    },\n    {\n      \"code\": \"require 'unirest'\\nresponse = Unirest.get \\\"https://www.exversion.com/api/v1/dataset/[DATASET ID]?key=[YOUR API KEY]&_limit=100\\\"\",\n      \"language\": \"ruby\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Strict Matches\"\n}\n[/block]\nBy default Exversion returns case insensitive partial matches to queries. But if you only want data returned that is an exact match, you can do so by specifying the column names to treat strictly with the _strict parameter.\n\n**Example Requests**\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"import requests\\n\\nr = requests.get(\\\"https://www.exversion.com/api/v1/dataset/[DATASET ID]?key=[YOUR API KEY]&firstname=Rob&lastname=Lowe&_strict=firstname,lastname\\\")\",\n      \"language\": \"python\"\n    },\n    {\n      \"code\": \"<?php\\n\\t$ch = curl_init('https://www.exversion.com/api/v1/dataset/[DATASET ID]?key=[YOUR API KEY]&firstname=Rob&lastname=Lowe&_strict=firstname,lastname');\\ncurl_setopt($ch, CURLOPT_RETURNTRANSFER, true);\\n$result = json_decode(curl_exec($ch));\\n?>\",\n      \"language\": \"php\"\n    },\n    {\n      \"code\": \"require 'unirest'\\nresponse = Unirest.get \\\"https://www.exversion.com/api/v1/dataset/[DATASET ID]?key=[YOUR API KEY]&firstname=Rob&lastname=Lowe&_strict=firstname,lastname\\\"\",\n      \"language\": \"ruby\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Changing Format Returned\"\n}\n[/block]\nBy default the API will return JSON, but queries can return other formats if you specify that in the url. Please contact support to request specific formats.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"https://exversion.com/api/v1/dataset/xml/[DATASET ID]?key=[YOUR API KEY]\\n\\nhttps://exversion.com/api/v1/dataset/json/[DATASET ID]?key=[YOUR API KEY]\",\n      \"language\": \"html\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"A Word on XML\",\n  \"body\": \"XML has a stricter standard for column names than JSON. For example, names may not begin with a number in XML. As a result, if the data contains a column name that cannot be used as a valid element name in XML, Exversion will modify it to an appropriate variation before returning the data.\"\n}\n[/block]","excerpt":"","slug":"fetching-data","type":"basic","title":"Fetching Data"}
[block:api-header] { "type": "basic", "title": "GET /dataset/:dataset" } [/block] [block:parameters] { "data": { "h-0": "parameter", "h-1": "value", "0-0": "key", "0-1": "The API key associated with your account", "1-0": "_limit", "1-1": "Number of rows to return", "2-0": "_remove", "2-1": "Remove these columns from each row", "4-0": "[column_name]", "4-1": "Will return only rows where the value of this column matches", "3-0": "_page", "3-1": "Get more results by paginating them with a limit and a page parameter" }, "cols": 2, "rows": 5 } [/block] **Example Requests** [block:code] { "codes": [ { "code": "import requests\n\nr = requests.get(\"https://www.exversion.com/api/v1/dataset/[DATASET ID]?key=[YOUR API KEY]&_limit=100\")", "language": "python" }, { "code": "<?php\n\t$ch = curl_init('https://www.exversion.com/api/v1/dataset/[DATASET ID]?key=[YOUR API KEY]&_limit=100');\ncurl_setopt($ch, CURLOPT_RETURNTRANSFER, true);\n$result = json_decode(curl_exec($ch));\n?>", "language": "php" }, { "code": "require 'unirest'\nresponse = Unirest.get \"https://www.exversion.com/api/v1/dataset/[DATASET ID]?key=[YOUR API KEY]&_limit=100\"", "language": "ruby" } ] } [/block] **Example Response** [block:code] { "codes": [ { "code": "{\"status\":200,\n \"message\":\"Success\",\n \"body\":[\n \t{\n \t\t\"_id\":\"FSBEQAKJQJH059881.299319683364711375720224963\",\n \t\t\"lobbyist_first_name\":\"James\",\n \t\t\"lobbyist_last_name\":\"Connolly\",\n \t\t\"filing_year\":\"2012\"\n\t\t},\n\t\t{\n \t\"_id\":\"FSBEQAKJQJH059857.653845592045361375720225585\",\n \t\"lobbyist_first_name\":\"James\",\n \t\"lobbyist_last_name\":\"Gilliam\",\n \t\"filing_year\":\"2012\"\n \t},\n\t\t{\n \t\t\"_id\":\"FSBEQAKJQJH05984.6746827350097781375720228202\",\n \t\t\"lobbyist_first_name\":\"James\",\n \t\t\"lobbyist_last_name\":\"Alexander\",\n \t\t\"filing_year\":\"2012\"\n\t\t},\n\t\t{\n \t\t\t\"_id\":\"FSBEQAKJQJH059878.41251410109141375720234876\",\n \t\t\"lobbyist_first_name\":\"James\",\n \t\t\"lobbyist_last_name\":\"Banks\",\n \t\t\"filing_year\":\"2012\"\n\t\t},\n\t\t{\n \t\t\"_id\":\"FSBEQAKJQJH059890.543216294539121375720235255\",\n \t\t\"lobbyist_first_name\":\"James\",\n \t\t\"lobbyist_last_name\":\"Darnell\",\n \t\t\"filing_year\":\"2012\"\n\t\t},\n\t\t{\n \t\"_id\":\"FSBEQAKJQJH059884.74339911080541375720244224\",\n \t\"lobbyist_first_name\":\"James\",\n \t\"lobbyist_last_name\":\"Henn\",\n \t\"filing_year\":\"2012\"\n \t},\n\t]\n}", "language": "json" } ] } [/block] [block:api-header] { "type": "basic", "title": "Returning a Range of Values" } [/block] You can return all data that fits within a numerical range by submitting a max and min value within square brackets [block:code] { "codes": [ { "code": "https://exversion.com/api/v1/dataset/[DATASET ID]?key=xxx&age=[30:35]", "language": "html" } ] } [/block] To return only values that are greater than or only those that are less than a certain number, just leave off one end of the range in your query [block:code] { "codes": [ { "code": "https://exversion.com/api/v1/dataset/[DATASET ID]?key=xxx&age=[:35]", "language": "html" } ] } [/block] [block:code] { "codes": [ { "code": "https://exversion.com/api/v1/dataset/[DATASET ID]?key=xxx&age=[30:]", "language": "html" } ] } [/block] [block:callout] { "type": "danger", "title": "Strings Are Not Numbers!", "body": "Range queries only work on columns that have **numerical **data. It's very easy to accidentally load data into Exversion where numbers have been converted to strings. In some cases it may even be preferable (example: coordinates tend to do better stored as strings), but nevertheless these columns cannot be queried using ranges." } [/block] [block:api-header] { "type": "basic", "title": "Querying Inside a Column" } [/block] Exversion does not require an exact, case sensitive match. Filtering a column by "NY" will return all the rows where the value in that column is "NY" as well as rows where it is "Brooklyn, NY" or "New York, NY" However, some data on Exversion is multidimensional. A good example of this are datasets that contain columns with GeoJSON data in them. In these cases you can actually query within the column by switching from GET to POST **Example Requests** [block:code] { "codes": [ { "code": "import requests\nimport json\n\nurl = 'https://www.exversion.com/api/v1/dataset/'\npayload = {\"key\":[YOUR API KEY],\"query\":[{\"dataset\":[DATASET ID], \"params\":{\"properties.CNTRY_NAME\":\"Aruba\"}}]}\nr = requests.post(url, data=json.dumps(payload))", "language": "python" }, { "code": "<?php\n\t$post = json_encode(\n array('key'=>[YOUR API KEY],\n 'query'=>array(\n array('dataset'=>[DATASET ID],\n 'params'=>array(\n 'properties.CNTRY_NAME'=>\"Aruba\")\n )\n )\n )\n );\n\t\t\n\t$ch = curl_init('https://www.exversion.com/api/v1/dataset/');\ncurl_setopt($ch, CURLOPT_CUSTOMREQUEST, \"POST\");\ncurl_setopt($ch, CURLOPT_POSTFIELDS, $post);\ncurl_setopt($ch, CURLOPT_RETURNTRANSFER, true);\ncurl_setopt($ch, CURLOPT_HTTPHEADER, array(\n 'Content-Type: application/json',\n 'Content-Length: ' . strlen($post))\n );\n$result = json_decode(curl_exec($ch));\n?>", "language": "php" }, { "code": "require 'unirest'\nresponse = Unirest.post \"https://www.exversion.com/api/v1/dataset/\", \n\t\theaders:{ \"Accept\" => \"application/json\" }, \n parameters:{'key'=>[YOUR API KEY],\n 'query'=>[{'dataset'=>[DATASET ID],\n 'params'=>{'properties.CNTRY_NAME'=>\"Aruba\"}]}", "language": "ruby" } ] } [/block] This will return any row where the JSON dict in column properties has a attribute named CNTRY_NAME with a value of Aruba [block:api-header] { "type": "basic", "title": "Remove Columns From Results" } [/block] Some datasets might include more data than you really need. To remove unnecessary columns from the results returned, pass the column names as a comma separated list (no spaces). Note that this only removes the columns from your results, to remove them permanently from the dataset update the schema. **Example Requests** [block:code] { "codes": [ { "code": "import requests\n\nr = requests.get(\"https://www.exversion.com/api/v1/dataset/[DATASET ID]?key=[YOUR API KEY]&_remove=lobbyist_first_name,filing_year\")", "language": "python" }, { "code": "<?php\n\t$ch = curl_init('https://www.exversion.com/api/v1/dataset/[DATASET ID]?key=[YOUR API KEY]&_remove=lobbyist_first_name,filing_year');\ncurl_setopt($ch, CURLOPT_RETURNTRANSFER, true);\n$result = json_decode(curl_exec($ch));\n?>", "language": "php" }, { "code": "require 'unirest'\nresponse = Unirest.get \"https://www.exversion.com/api/v1/dataset/[DATASET ID]?key=[YOUR API KEY]&_limit=100\"", "language": "ruby" } ] } [/block] [block:api-header] { "type": "basic", "title": "Strict Matches" } [/block] By default Exversion returns case insensitive partial matches to queries. But if you only want data returned that is an exact match, you can do so by specifying the column names to treat strictly with the _strict parameter. **Example Requests** [block:code] { "codes": [ { "code": "import requests\n\nr = requests.get(\"https://www.exversion.com/api/v1/dataset/[DATASET ID]?key=[YOUR API KEY]&firstname=Rob&lastname=Lowe&_strict=firstname,lastname\")", "language": "python" }, { "code": "<?php\n\t$ch = curl_init('https://www.exversion.com/api/v1/dataset/[DATASET ID]?key=[YOUR API KEY]&firstname=Rob&lastname=Lowe&_strict=firstname,lastname');\ncurl_setopt($ch, CURLOPT_RETURNTRANSFER, true);\n$result = json_decode(curl_exec($ch));\n?>", "language": "php" }, { "code": "require 'unirest'\nresponse = Unirest.get \"https://www.exversion.com/api/v1/dataset/[DATASET ID]?key=[YOUR API KEY]&firstname=Rob&lastname=Lowe&_strict=firstname,lastname\"", "language": "ruby" } ] } [/block] [block:api-header] { "type": "basic", "title": "Changing Format Returned" } [/block] By default the API will return JSON, but queries can return other formats if you specify that in the url. Please contact support to request specific formats. [block:code] { "codes": [ { "code": "https://exversion.com/api/v1/dataset/xml/[DATASET ID]?key=[YOUR API KEY]\n\nhttps://exversion.com/api/v1/dataset/json/[DATASET ID]?key=[YOUR API KEY]", "language": "html" } ] } [/block] [block:callout] { "type": "warning", "title": "A Word on XML", "body": "XML has a stricter standard for column names than JSON. For example, names may not begin with a number in XML. As a result, if the data contains a column name that cannot be used as a valid element name in XML, Exversion will modify it to an appropriate variation before returning the data." } [/block]