As odd as it may sound, WordPress’ XML-RPC system is built on others. This makes sense from a development standpoint – why reinvent the wheel when others have done such a great job? But it can be incredibly confusing and downright frustrating when you start working with the WordPress API and have to turn to metaWeblog’s or Blogger’s documentation to figure something out.
The fragmentation of the API documentation is what turns many off from XML-RPC development at first. That said, the APIs are stitched together quite elegantly when you look at the server code. To make things simpler, we’ll deal with one set of API calls at a time. The most basic are the metaWeblog calls, so we’ll start there.
metaWeblog.newPost
Function: Creates a new post on your blog.
Parameters:
- Blog ID – For use in multisite installations, typically 0 for single sites
- Username – WordPress username
- Password – WordPress password
- Content – Your blog post defined as an associate array with the following fields
- ‘post_type’ – ‘post’ or ‘page’
- ‘wp_slug’ – Post slug (optional)
- ‘wp_password’ – Post password (optional)
- ‘wp_page_parent_id’ – ID of the parent post (optional)
- ‘wp_page_order’ – Menu order (optional)
- ‘wp_author_id’ – Identify an author other than the user posting the request (optional)
- ‘title’ – Post title
- ‘description – Post body content
- post-type_status – Set the post/page/custom status to draft, private, publish, publish, or pending
- ‘mt_excerpt’ – Post excerpt
- ‘mt_text_more’ – Text for the Read More link
- ‘mt_keywords’ – Tags
- ‘mt_allow_comments’ – Set whether comments are open or closed
- ‘mt_allow_pings’ – Same settings as ‘mt_allow_comments’
- ‘mt_tb_ping_urls’ – An array of the URLs you want to ping on publication
- ‘date_created_gmt’ – The publication date for the post
- ‘dateCreated’ – Same as above … use one or the other
- ‘categories’ – An array of categories for the post.
- Publish – The status you want the post to have, either publish or draft
Returns: ID of the post you just created
metaWeblog.editPost
Function: Allows you to update the content of a published post.
Parameters:
- ID of the post you want to edit
- WordPress username
- WordPress password
- Post content (same as for metaWeblog.newPost) – Only send the parameters you want to change.
- Publish – The status you want the post to have, either publish or draft
Returns: True – yup, that’s it. Just the Boolean value true.
metaWeblog.getPost
Function: Gets the value of a given post on the blog.
Parameters:
- ID of the post you want to retrieve
- WordPress username
- WordPress password
Returns: An associative array of the post content.
- ‘dateCreated’ – Post publication date
- ‘userid’ – ID of the post author
- ‘postid’ – ID of the post itself
- ‘description’ – Post content
- ‘title’ – Post title
- ‘link’ – Post permalink
- ‘permaLink’ – Post permalink
- ‘categories’ – Array of post categories
- ‘mt_excerpt’ – Post excerpt
- ‘mt_text_more’ – Read More text
- ‘mt_allow_comments’ – Whether comments are open or closed
- ‘mt_allow_pings’ – Whether pings are open or closed
- ‘mt_keywords’ – Array of post tags
- ‘wp_slug’ – Post slug
- ‘wp_password’ – Post password
- ‘wp_author_id’ – ID of the post author
- ‘wp_author_display_name’ – Display name of the post author
- ‘date_created_gmt’ – Post publication date (as GMT time)
- ‘post_status’ – Post publication status
- ‘custom_fields’ – Array of custom fields
- ‘sticky’ – Whether or not the post is marked as “sticky”
metaWeblog.getRecentPosts
Function: Gets an array of recent posts on the blog – similar to metaWeblog.getPost, but it returns as many posts as you want.
Parameters:
- ID of the blog you’re working with (usually 0 for a single site)
- WordPress username
- WordPress password
- Number of posts you want to return
Returns: An array where each element of the array is itself an array containing the content of a post. See metaWeblog.getPost for a description of the post content array.
metaWeblog.getCategories
Function: Gets a list of categories used by the blog.
Parameters:
- ID of the blog you’re working with (usually 0 for a single site)
- WordPress username
- WordPress password
Returns: Returns a simple array, where each element is an associate array defining the category:
- ‘categoryID’ – ID of the category
- ‘parentID’ – ID of the category’s parent
- ‘description’ – Name of the category
- ‘categoryDescription’ – Description of the category
- ‘categoryName’ – Name of the category
- ‘htmlUrl’ – Category permalink
- ‘rssUrl’ – RSS feed for the category
metaWeblog.newMediaObject
Function: Uploads a media file to your blog, based on your media settings.
Parameters:
- ID of the blog you’re uploading to (usually 0 for a single site)
- WordPress username
- WordPress password
- Upload data (array)
- Upload name
- File type
- File bit data (the file itself)
Returns: An array with elements file (file name), url (file url), and type.
Thank you, this post saved me a ton of time digging for the api docs.
dateCreated and/or date_created_gmt will not post as such. if you run a script with this, the post date yeilds the date of the script that ran, not the givent date
i.e.
if i send $pubdate = “2011-05-03 04:23:22
‘date_created_gmt’=>$datetime->format(DateTime::ISO8601),
still will post, but the date created will still be todays (or whenever the script was run)
is there something else that needs to be done inorder to make this work?
Skip, I’d need to see your code to be sure (as in the entire request), but if either “date_created_gmt” or “dateCreated” are set, WordPress will use those values instead of the current system date. If they’re both missing, then it uses the current system time.
Take a look at the core code file “/wp-includes/class-wp-xmlrpc-server.php” around lines 2377-2388 and you’ll see what I mean.
Hi Eric,
I am having the exact same issue with the date, WP just assumes the current date although i am sending the dates in the request:
$data = strtotime($data);
$data = gmdate(“Ymd\TH:i:s”,$data);
$content['date_created'] = $data;
I must confess i am at a complete loss. I have checked the xmlrpc-server.php file and it appears to take in consideration the parameters we send…however, it doesn’t do so.
Skip, did you find any solution?
Hi, I was just wondering, what is the format of the date? Can you give me a sample php code that formats the date. I always get an error when I am using the normal date time format. Thank you
metaWeblog.getRecentPosts in the WordPress API doesn’t return as many posts as you want (as per description). It returns a set of summaries of posts or pages. The data returned is not the same as that returned from metaWeblog.getPost.
The third parameters of `metaWeblog.getRecentPosts` is an integer that defines the number of posts returned by the query. If you don’t define this integer, the request will always return a set of 10 posts (because 10 is the default value).
The call will return an array of recent posts; each post will be an object defining:
‘dateCreated’, ‘userid’, ‘postid’, ‘description’, ‘title’, ‘link’, ‘permaLink’, ‘categories’, ‘mt_excerpt’, ‘mt_text_more’ , ‘mt_allow_comments’, ‘mt_allow_pings’, ‘mt_keywords’, ‘wp_slug’, ‘wp_password’, ‘wp_author_id’, ‘wp_author_display_name’, ‘date_created_gmt’, ‘post_status’, ‘custom_fields’, and ‘wp_post_format’. The only field missing from that list that is returned by `metaWeblog.getPost` is ‘sticky’.
Thanks a ton for this. This was even hard to find in metaweblog’s documentation. esp. “tags” part which got me stuck for hours.
Cheers.
After two days discovering WordPress XML-RPC the hard way, I finally found your post. Thank you very much, it saved me a lot of time.
I can’t help saying thank you so much. This has saved me so much time. I can’t believe that there is no official documents on this thing.