Queries on data provided

[Joe]

Hi,

As per an earlier discussion in this forum I'm involved in an
initiative to integrate my website with GlobalGiving via their
excellent API in a way that encourages my users to make donations to a
selection of GlobalGiving's microfinance projects.

I'm just at the point of instructing my developer and wanted to
clarify a few points so I can be precise in what I'm asking them to do
for me. Some of the items below are questions, while some are really
just me stating my assumptions so you can correct me if I'm wrong:

1) Using large versions of the default project images - It looks like
the 'Get Specific Project' call will return a URL for a default image
for that project and this URL follows a predictable pattern for all
projects, e.g. https://www.globalgiving.org/pfil/4308/pict.jpg.

The size of the default image is smaller than I'd like, but larger
versions of the default images are available, e.g.
https://www.globalgiving.org/pfil/4308/pict_large.jpg. Again the URL
follows a predictable pattern, so would it be acceptable for me to use
this larger image on my site or would I be infringing GlobalGiving's
intellectual property/copyright by using images that don't strictly
come via the API?

As an aside, the large versions of the images are not a standard size
(unlike the smaller default image provided via the API), so if it was
acceptable for me to use these larger images I would need my developer
to ensure they displayed correctly on my site regardless of their size/
proportions.

2) Using images other than the default project images - Aside from the
default image for a project there is often also a variety of other
images displayed for a project on GlobalGiving's site, both in the
general project information and also in the progress reports.

These images are great and really engaging for users and I'd love to
incorporate them on my site somehow, but the URLs for these images
don't appear to be included in API calls like 'Get Specific Project'
and 'Get Progress Report for Specific Project'. Also they don't seem
to follow a predictable URL format, e.g. http://cloud.globalgiving.org/pfil/4308/ph_4308_15246.jpg.
One possible option would be for me to manually identify and then
store these images on my site, but again would I be infringing
GlobalGiving's IP by doing this?

As an aside, the images are really integral to engaging people and I
think if a project's images (particularly their default image) was of
poor quality or content then it would put me off listing that project
on my site.

3) Submission of progress reports as attachments - If progress reports
are submitted by the project as a combination of text and attachments
(e.g. project #876) rather than just as text (e.g. #3666) it doesn't
look like URLs for these attachments don't come through via the API.
I'm keen to show progress reports on my site so I would be put off
from including a project on my site if they're submitting part of
their progress reports as an attachment.

4) Additional Documentation and Resources - Similar to 3 above, many
projects include links to Additional Documentation (e.g. PDFs) and
Resources (e.g. related links) and these don't appear to come across
in the 'Get Specific Project' API call, which is a shame.

5) Project expiry - From a technical perpective I understand that if
'active = true' for a project then the project is accepting donations
and if 'active = false' then the project is not accepting donations
and I will ensure we filter out any of the latter projects when people
on my site are looking to make donations to projects.

I do intend to build some functionality on my site that shows users a
history of the projects they've donated to. Can you confirm that, even
if a project is no longer accepting donations, the data about the
project would still continue to be made available via the API? If
there is an expiry of some sort for projects to appear in the API can
you let me know the rules of the expiry?

Any feedback/advice would be much appreciated (please bear in mind I
don't come from a development background).

Best,

Joe

[Steve R.]

Joe, You ask excellent questions and I will respond inline below:

On Aug 16, 9:28 am, Joe <joe.ly...@gmail.com> wrote:
> Hi,

>
>
> 1) Using large versions of the default project images - It looks like
> the 'Get Specific Project' call will return a URL for a default image
> for that project and this URL follows a predictable pattern for all

> projects, e.g.https://www.globalgiving.org/pfil/4308/pict.jpg.

>
> The size of the default image is smaller than I'd like, but larger

> versions of the default images are available, e.g.https://www.globalgiving.org/pfil/4308/pict_large.jpg. Again the URL

> follows a predictable pattern, so would it be acceptable for me to use
> this larger image on my site or would I be infringing GlobalGiving's
> intellectual property/copyright by using images that don't strictly
> come via the API?
>
> As an aside, the large versions of the images are not a standard size
> (unlike the smaller default image provided via the API), so if it was
> acceptable for me to use these larger images I would need my developer
> to ensure they displayed correctly on my site regardless of their size/
> proportions.
>

>>>>>> It is ok to use the large images... BUT, they are variable size and will continue to be because they essentially reflect what ever the project leader uploads. We cannot guarantee quality for this reason - all the projects on our site use our platform as a CMS, so load their own content. We try to give them guidlines for image quality, and it has improved greatly.

Furthermore, you have touched on an excellent idea for improving our
API, to add additional attributes to the project that include
different sized images, rather than the default pict.ext (note, not
all pictures will be jpg, again it depends on what type of file the
project leader uploads).

> 2) Using images other than the default project images - Aside from the
> default image for a project there is often also a variety of other
> images displayed for a project on GlobalGiving's site, both in the
> general project information and also in the progress reports.
>
> These images are great and really engaging for users and I'd love to
> incorporate them on my site somehow, but the URLs for these images
> don't appear to be included in API calls like 'Get Specific Project'
> and 'Get Progress Report for Specific Project'. Also they don't seem

> to follow a predictable URL format, e.g.http://cloud.globalgiving.org/pfil/4308/ph_4308_15246.jpg.

> One possible option would be for me to manually identify and then
> store these images on my site, but again would I be infringing
> GlobalGiving's IP by doing this?
>
> As an aside, the images are really integral to engaging people and I
> think if a project's images (particularly their default image) was of
> poor quality or content then it would put me off listing that project
> on my site.
>

I addressed quality above. You would not be infringing on IP if you
used these images, as long as they were attributed to GlobalGiving
(similar to creative commons licensing). And also, again, this is an
excellent area for an API enhancement, to give zero or more additional
photos, and in varying sizes as well. For instance we could deliver
two links: a thumbnail size, and a full size. Open to suggestions for
what would be most useful.

> 3) Submission of progress reports as attachments - If progress reports
> are submitted by the project as a combination of text and attachments
> (e.g. project #876) rather than just as text (e.g. #3666) it doesn't
> look like URLs for these attachments don't come through via the API.
> I'm keen to show progress reports on my site so I would be put off
> from including a project on my site if they're submitting part of
> their progress reports as an attachment.
>

We can look into providing links for attachments - most attachments
that come with progress reports are images, but there is always the
occasional PDF file (a report of some sort) that project leaders
upload as supporting documentation. If we included links to
documents, and images, in the api results, would this help?

> 4) Additional Documentation and Resources - Similar to 3 above, many
> projects include links to Additional Documentation (e.g. PDFs) and
> Resources (e.g. related links) and these don't appear to come across
> in the 'Get Specific Project' API call, which is a shame.
>

You are the first to have asked for this, but its certainly a
possibility to add.
What I would ask of you is to prioritize all the things you have
suggested above, because as a small team here at GlobalGiving, it
can't all be done at once.

> 5) Project expiry - From a technical perpective I understand that if
> 'active = true' for a project then the project is accepting donations
> and if 'active = false' then the project is not accepting donations
> and I will ensure we filter out any of the latter projects when people
> on my site are looking to make donations to projects.
>
> I do intend to build some functionality on my site that shows users a
> history of the projects they've donated to. Can you confirm that, even
> if a project is no longer accepting donations, the data about the
> project would still continue to be made available via the API? If
> there is an expiry of some sort for projects to appear in the API can
> you let me know the rules of the expiry?
>

Projects will continue to be delivered through the API at this time,
but will have (as you noticed) active = false, and in addition will
have a status of retired or funded. These different status mean
project was retired and did not raise ANY funds, vs it met its funding
goal (one way or another) and received at least some funds from
globalgiving (funded).

[Joe]

Thanks for your reply Steve, it all made sense and will really help me
instruct my developer.

From the ideas we've discussed here my wishlist for future API
development would be as follows (in order of priority):

1) Adding additional attributes to the project that include different
sized images

I've worked at a couple of book publishers in the past and they
provide distributors/retailers with data about their products using
the ONIX international standard (an XML feed). That standard includes
links to a selection of cover images in very specific sizes and
formats, if you go to http://assets.cambridge.org/ then search for
9780521195331 you'll see a sample of these cover images for a
Cambridge University Press title. There's thumbnails in GIF and JPG,
medium size 'Website covers' in GIF and JPG, and a large size JPG, and
these are the images that will get included in the XML feed and used
by booksellers such as Barnes & Noble
http://search.barnesandnoble.com/Networks-Crowds-and-Markets/David-Easley/e/9780521195331/.

Now I'm not saying you need to copy exactly what book publishers do,
but it's a useful example and does underline the importance of having
a consistent image size when that image is being used by a large
number of third-parties. Given you've got images being submitted by
project leaders in different orientations (portrait/landscape) then
you won't be in a position to fix both the height and width of the
images you're providing without squashing them, but you could fix one
or the other. I don't have a lot of web design experience but a
designer could probably tell you if it's more desirable to fix the
height or width of an image when designing a page to display images of
varying orientations.

So my first priority would be for you to add an additional attribute
to the project for a medium sized image in addition to the thumbnail
(perhaps fixing the height or width at around 250-350 pixels?).

2) Adding additional attributes to the progress reports that include
links for attachments

The progress reports from projects are one of the most attractive
features about GlobalGiving's model, they offer a real sense of
transparency to donators so it could be frustrating for a donator to
see 'Attached is the Spring update...' or 'To read the rest of our
annual newsletter...' and not be able to see the relevant attachment
on my site. There seem to be two common types of attachments to
progress reports as you say, images and PDFs. The PDFs would be the
priority for me, and I could live without the images if that made this
development available sooner.

If these attributes weren't added to the API it would require me to
review every project prior to making it available from my own site, as
I would try to omit an projects uploading progress reports as
attachments. But this is far from ideal, as a project can start
uploading progress reports as attachments at any time making
administration of this a bit of a pain.

3) Adding additional attributes to the projects that include
additional photos

The photos of these projects are often really good and help engage
donators, so I would like to see them made available via the API, but
only if they were provided in different and consistent sizes as
discussed in point 1 above, and getting the default image available in
different and consistent sizes would be my priority, so I would list
this as a 'nice to have' rather than a 'must have' like points 1 & 2
above.

4) Adding additional attributes to the projects that include links for
attachments

This is similar to number 2, but I'm referring to the attachments
uploaded against the general project information rather than the
progress reports. This is a much lower priority for me, as I feel the
generic data that each project must provide (e.g. Summary, What is the
issue, problem, or challenge? How will this project solve this
problem?) is sufficiently detailed enough for a donator to assess a
project by. So displaying attachments uploaded against a project is
not essential, and again I would list this as a 'nice to have' rather
than a 'must have' like points 1 & 2 above.

If the ideas seem viable would it be possible to get a timeline on
points 1 or 2? The bulk of my site's development will be happening in
early-mid September with deployment in October so I'll need to get my
developers looking at interim workarounds to address points 1 or 2 if
they won't be in place by early September.

Thanks and best,

Joe

[Kevin Conroy]

Hi Joe,

Thanks for all of your wonderful feedback, suggestions, and references. We are trying to make our API as useful as possible so it's great to get actionable feedback on how we can improve it. 

I've added it to our product backlog and have put it at a high priority. We schedule all of our work on a monthly basis at the start of each month. We'll be sure to let you know when we expect to have it done once we know for sure.

That being said, in the mean time there are a couple of work arounds that I can offer for #1 and 2.

1) All projects have several different sized images all of which follow a predictable naming patten. Note that I'll assume that the image is in JPG to demonstrate the patterns as the vast majority of projects are. However, as Steve noted, it is possible that it's in gif format, but this tends to be for older projects. 

The different files are as follows:

http://www.globalgiving.org/pfil/{PROJECT_ID}/pict.jpg

http://www.globalgiving.org/pfil/{PROJECT_ID}/pict_thumbnail.jpg

http://www.globalgiving.org/pfil/{PROJECT_ID}/pict_grid1.jpg

http://www.globalgiving.org/pfil/{PROJECT_ID}/pict_med.jpg

http://www.globalgiving.org/pfil/{PROJECT_ID}/pict_grid7.jpg

http://www.globalgiving.org/pfil/{PROJECT_ID}/pict_large.jpg

http://www.globalgiving.org/pfil/{PROJECT_ID}/pict_original.jpg

Here's the information about them (WxH in pixels):

pict.jpg = fixed size of 176x114 

pict_thumbnail.jpg = fixed size of 80x52

pict_grid1.jpg = maximum dimensions of 75x75 - best fit, may be smaller in one dimension

pict_med.jpg = maximum dimensions of 300x220  - best fit, may be smaller in one dimension.

pict_grid7.jpg = maximum dimensions 540x405 - best fit, may be smaller in one dimension

pict_large.jpg = maximum dimensions 1024x1024 - may be smaller in either or both dimensions. Will fit larger images to 1024 on one side. Smaller images are not scaled up.

pict_original.jpg = The original image file that was uploaded to GlobalGiving and was used to generate the other versions.

For grid1, med, and grid7 these are all "best fit" images.  For instance, the grid7 size scales the image to fit one of those dimensions, so landscape pictures are 540 px wide and portrait photos are 405 px tall. The other dimensions varies based on the aspect ratio of the original photo, but it will never exceed 540x405. If you make a container of this size, the grid7 image is effectively a "best fit" for this container without cropping. The same applied to grid1 and med but at their respective dimensions.

Based on what you've said, I think pict_med.jpg will probably be the most helpful version for you to have, but you are of course welcome to use any/all of them.

Additionally, all of these patterns also work with the cloud.globalgiving.org domain, which is an Amazon Cloudfront mirror of our images providing world-wide geographic distribution. Depending on where you are located, Cloudfront (cloud) may provide a faster transfer time than the primary (www) GlobalGiving servers.

To your point, we'll work on adding these different URLs to the API so that you don't have to reverse engineer them from the main pict.jpg URL. In the mean time, though, reverse engineering could work to get your project moving forward.

2) With regard to progress reports, all projects have an RSS feed that we update nightly. The RSS feed has the complete text as well as pictures and links to attachments. 

The pattern for the RSS feed is not quit as straightforward as the images but it is predictable:

http://www.globalgiving.org/pr/{PROJECT ID ROUNDED UP TO NEXT INTEGER DIVISIBLE BY 100 WITH NO REMAINDER}/proj{PROJECT ID}.rss

Here are some examples:

Project #65 -> http://www.globalgiving.org/pr/100/proj65.rss

Project #1234 -> http://www.globalgiving.org/pr/1300/proj1234.rss

Project #5671 -> http://www.globalgiving.org/pr/5700/proj5671.rss

That being said, I understand that parsing the RSS feed and pulling out the desired information adds yet another layer of complexity that would be easily avoided by having us simply add the information that you've pointed out to the API. I completely agree and we'll work on fixing this on the API. I'm just mentioning the RSS feeds since it's a way that you can systematically get it right now.

Kevin Conroy
E-mail: kevin...@gmail.com

Joe

--
You received this message because you are subscribed to the Google Groups "GlobalGiving API" group.
To post to this group, send email to globalgi...@googlegroups.com.
To unsubscribe from this group, send email to globalgiving-a...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/globalgiving-api?hl=en.