{"_id":"5447ea9c0319802200fc06e6","version":{"_id":"53844558a43e08da4677be12","__v":8,"project":"53844557a43e08da4677be0e","createdAt":"2014-05-27T07:57:12.136Z","releaseDate":"2014-05-27T07:57:12.136Z","categories":["53844558a43e08da4677be13","538619e1ef91f96d49aa1a0b","541e82877eb16bb64f83c0ca","5445a073c3eb3808000c76b2","5445a098c3eb3808000c76b3","54bb05ab522f03150054d9e8","54bb05cf9741c81500078f73","55b7d0e5568be2230092bb92"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"false","version_clean":"1.0.0","version":"1.0"},"__v":0,"editedParams":true,"is_link":false,"category":{"_id":"5445a098c3eb3808000c76b3","project":"53844557a43e08da4677be0e","version":"53844558a43e08da4677be12","__v":3,"pages":["5432e4d15b5b950800f4edc9","5445c719bfa07c0800f3a12e","5447ea9c0319802200fc06e6","54512f34a66f020800dbab10"],"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2014-10-20T23:54:00.481Z","from_sync":false,"order":5,"slug":"additional-functionality","title":"Additional functionality"},"editedParams2":true,"project":"53844557a43e08da4677be0e","user":"5432d74e8780d4080074d772","updates":[],"next":{"pages":[],"description":""},"createdAt":"2014-10-22T17:34:20.406Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[{"code":"{\"chart_url\":\"https://s3.amazonaws.com/knowtify-charts/xxxxxxx.png\"}","language":"json","status":200,"name":""}]},"settings":"","try":false,"basic_auth":false,"method":"post","auth":"never","params":[{"_id":"5447ea9c0319802200fc06ea","ref":"","in":"body","required":true,"desc":"This image is going in a shared folder so please use a unique string","default":"","type":"string","name":"filename"},{"_id":"5447ea9c0319802200fc06e9","ref":"","in":"body","required":true,"desc":"Creates an element with this id before running the D3 script","default":"","type":"string","name":"chart_id"},{"_id":"5447ea9c0319802200fc06e8","ref":"","in":"body","required":true,"desc":"URL to your D3 script.","default":"","type":"string","name":"d3_script_url"},{"_id":"5447ea9c0319802200fc06e7","ref":"","in":"body","required":false,"desc":"Object of optional key/values of variables to be used in your D3 script.","default":"{}","type":"string","name":"vars"}],"url":"http://charts.knowtify.io/d3"},"isReference":false,"order":2,"body":"[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Example request JSON\"\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\t\\\"filename\\\":\\\"{your_public_key}_{chart_name}\\\",\\n  \\t\\\"chart_id\\\":\\\"pie\\\",\\n \\t\\t\\\"d3_script_url\\\":\\\"{your_script_url}\\\",\\n  \\t\\\"vars\\\":{\\n      \\t\\\"percent\\\":73,\\n      \\t\\\"label\\\":\\\"Satisfied Users\\\",\\n    \\t\\t\\\"w\\\":400,\\n        \\\"h\\\":300\\n    }     \\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"What is chart_id?\"\n}\n[/block]\nIn D3.js you typically append an SVG element to an existing DOM element. Our script adds a div to the document with the chart_id as the id. This element is also needed to create a bounding box for the screenshot after the D3 script runs.\n\nIf your chart_id is set to \"pie\", the document will look something like this before running your script.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<!DOCTYPE HTML>\\n<html>\\n<head>\\n    <!-- Header Boilerplate -->\\n</head>\\n<body>\\n  <div id=\\\"pie\\\"></div>\\n</body>\\n</html>\",\n      \"language\": \"html\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Filenames\"\n}\n[/block]\nTo make our API as easy as possible to use, we don't require any authentication. The downside is all our chart images will live in the same S3 bucket. So if you use a generic filename then it's possible for someone to overwrite it! To avoid that, please use your Knowtify Public Token found in http://www.knowtify.io/settings as a prefix to your filenames. Alternatively, you could use a unique randomly generated string as a prefix.\n\nExample filenames with user ids...\n- 362496ce22c4284348691388a099f391_1\n- 362496ce22c4284348691388a099f391_2\n- 362496ce22c4284348691388a099f391_3\n\nThe urls of the above filenames would be...\n- https://s3.amazonaws.com/knowtify-charts/362496ce22c4284348691388a099f391_1.png\n- https://s3.amazonaws.com/knowtify-charts/362496ce22c4284348691388a099f391_2.png\n- https://s3.amazonaws.com/knowtify-charts/362496ce22c4284348691388a099f391_3.png\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Charts get deleted after 7 days\"\n}\n[/block]\nIn order for us to provide this service for free, charts automatically get deleted after 7 days. You are free to download charts and host them on your own servers if it's important that they  are available for longer than a week.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"This is beta!\"\n}\n[/block]\nThis feature is still in beta so errors happen. We plan to introduce things like better error handling, batch requests, authentication and more in the future. If you plan to use this for production emails I'd just recommend taking a few precautions.\n\n- Don't send a large number of requests at once. Generating these charts is fairly resource intensive and we haven't load tested our servers yet so if you send us too many concurrent requests, we may drop some of them.\n- Because errors happen, look for a 200 response with a chart_url before assuming your request properly generated a chart.\n- Start slow. Instead of generating 1,000 charts at once, start with 10 and ramp up.\n- Verify that your charts are being plotted as expected. If not please email me at dane:::at:::knowtify.io to report a bug.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Troubleshooting\"\n}\n[/block]\nWe don't currently have an easy way to troubleshoot your D3 script if it doesn't generate an image as expected but feel free to email me at dane@knowtify.io while we work on improving the API.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"CSS stylesheets\"\n}\n[/block]\nComing soon!\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Chart background color\"\n}\n[/block]\nStylesheets are definitely better for this but here is a simple hack that adds a colored SVG rectangle to the chart behind all of your chart elements. \n\n- Be sure to adjust the width and height to match the chart dimensions.\n- The fill is the background color.\n- Be sure to add your rectangle immediately after adding the svg element.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"var svg = d3.select(\\\"#chart\\\").append(\\\"svg\\\")\\n    .attr(\\\"width\\\", 800)\\n    .attr(\\\"height\\\", 300);\\n\\n//The following js adds a background\\nsvg.append(\\\"rect\\\")\\n  .attr(\\\"width\\\", 800)\\n  .attr(\\\"height\\\", 300)\\n  .attr(\\\"fill\\\", '#f2f2f2');\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Sample D3 charts\"\n}\n[/block]\nComing soon!\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Test this API\"\n}\n[/block]\nWe have a Postman collection that you can use to test this API. Simply go to the body and fill in the attributes. \n\nhttps://www.getpostman.com/collections/3a8dfcdfcb341196f719","excerpt":"Generate dynamic D3js charts that get converted to PNG images that can be inserted into emails. (scroll down for examples)","slug":"d3js-charts-for-your-email","type":"endpoint","title":"D3js charts for your email"}

postD3js charts for your email

Generate dynamic D3js charts that get converted to PNG images that can be inserted into emails. (scroll down for examples)

Definition

{{ api_url }}{{ page_api_url }}

Parameters

Body Params

filename:
required
string
This image is going in a shared folder so please use a unique string
chart_id:
required
string
Creates an element with this id before running the D3 script
d3_script_url:
required
string
URL to your D3 script.
vars:
string{}
Object of optional key/values of variables to be used in your D3 script.

Result Format


Documentation

[block:api-header] { "type": "basic", "title": "Example request JSON" } [/block] [block:code] { "codes": [ { "code": "{\n \t\"filename\":\"{your_public_key}_{chart_name}\",\n \t\"chart_id\":\"pie\",\n \t\t\"d3_script_url\":\"{your_script_url}\",\n \t\"vars\":{\n \t\"percent\":73,\n \t\"label\":\"Satisfied Users\",\n \t\t\"w\":400,\n \"h\":300\n } \n}", "language": "json" } ] } [/block] [block:api-header] { "type": "basic", "title": "What is chart_id?" } [/block] In D3.js you typically append an SVG element to an existing DOM element. Our script adds a div to the document with the chart_id as the id. This element is also needed to create a bounding box for the screenshot after the D3 script runs. If your chart_id is set to "pie", the document will look something like this before running your script. [block:code] { "codes": [ { "code": "<!DOCTYPE HTML>\n<html>\n<head>\n <!-- Header Boilerplate -->\n</head>\n<body>\n <div id=\"pie\"></div>\n</body>\n</html>", "language": "html" } ] } [/block] [block:api-header] { "type": "basic", "title": "Filenames" } [/block] To make our API as easy as possible to use, we don't require any authentication. The downside is all our chart images will live in the same S3 bucket. So if you use a generic filename then it's possible for someone to overwrite it! To avoid that, please use your Knowtify Public Token found in http://www.knowtify.io/settings as a prefix to your filenames. Alternatively, you could use a unique randomly generated string as a prefix. Example filenames with user ids... - 362496ce22c4284348691388a099f391_1 - 362496ce22c4284348691388a099f391_2 - 362496ce22c4284348691388a099f391_3 The urls of the above filenames would be... - https://s3.amazonaws.com/knowtify-charts/362496ce22c4284348691388a099f391_1.png - https://s3.amazonaws.com/knowtify-charts/362496ce22c4284348691388a099f391_2.png - https://s3.amazonaws.com/knowtify-charts/362496ce22c4284348691388a099f391_3.png [block:api-header] { "type": "basic", "title": "Charts get deleted after 7 days" } [/block] In order for us to provide this service for free, charts automatically get deleted after 7 days. You are free to download charts and host them on your own servers if it's important that they are available for longer than a week. [block:api-header] { "type": "basic", "title": "This is beta!" } [/block] This feature is still in beta so errors happen. We plan to introduce things like better error handling, batch requests, authentication and more in the future. If you plan to use this for production emails I'd just recommend taking a few precautions. - Don't send a large number of requests at once. Generating these charts is fairly resource intensive and we haven't load tested our servers yet so if you send us too many concurrent requests, we may drop some of them. - Because errors happen, look for a 200 response with a chart_url before assuming your request properly generated a chart. - Start slow. Instead of generating 1,000 charts at once, start with 10 and ramp up. - Verify that your charts are being plotted as expected. If not please email me at dane@knowtify.io to report a bug. [block:api-header] { "type": "basic", "title": "Troubleshooting" } [/block] We don't currently have an easy way to troubleshoot your D3 script if it doesn't generate an image as expected but feel free to email me at dane@knowtify.io while we work on improving the API. [block:api-header] { "type": "basic", "title": "CSS stylesheets" } [/block] Coming soon! [block:api-header] { "type": "basic", "title": "Chart background color" } [/block] Stylesheets are definitely better for this but here is a simple hack that adds a colored SVG rectangle to the chart behind all of your chart elements. - Be sure to adjust the width and height to match the chart dimensions. - The fill is the background color. - Be sure to add your rectangle immediately after adding the svg element. [block:code] { "codes": [ { "code": "var svg = d3.select(\"#chart\").append(\"svg\")\n .attr(\"width\", 800)\n .attr(\"height\", 300);\n\n//The following js adds a background\nsvg.append(\"rect\")\n .attr(\"width\", 800)\n .attr(\"height\", 300)\n .attr(\"fill\", '#f2f2f2');", "language": "javascript" } ] } [/block] [block:api-header] { "type": "basic", "title": "Sample D3 charts" } [/block] Coming soon! [block:api-header] { "type": "basic", "title": "Test this API" } [/block] We have a Postman collection that you can use to test this API. Simply go to the body and fill in the attributes. https://www.getpostman.com/collections/3a8dfcdfcb341196f719

User Information

Try It Out

post
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}