Philadelphia Public Art @philart.net

API

Welcome to the documentation page for the Philadelphia Public Art API @philart.net, a read-only, RESTful JSON API which exists to enable application developers and data miners to retrieve and use the same data that drives the main website.

Disclaimers

This API is offered as-is. It is a part-time hobby project of the webmaster, and as such offers no guarantees of up-time, bug-free operation, or data accuracy. The data returned may be in a partial state during updates, which are both frequent and unscheduled. This API is not intended, nor should it be used, as the basis of any commercial application. The webmaster is not responsible for your use or misuse of the API or for any financial or other harm that may come from your use of it.

Backwards Compatibility and Versioning

There will only ever be one supported version of the API active at any time. However, the webmaster does endavor to make the current version as accurate and bug-free as possible, and does promise that as changes are made or new features added, the API will stay as backwards compatible as possible, with every attempt made to avoid changes to structure or data meaning that would likely break existing applications.

Copyright

The copyright notice in the fine print of the footer of this page applies to all data supplied through, and images referenced by, the API on this site. The format of the positive JSON responses on this site is Copyright 2015, Christopher William Purdom. Permission is granted to use the JSON format in any way you choose, so long as you do not claim ownership for yourself.

Introduction

Head Types

The following types are currently supported in the head:

HATEOAS links

All HATEOAS links are in the form "links":[ {"rel":"x","href":"y"}] where the first element always has a rel of "self" and the href is a fully qualified URL. For all the head types listed below (art, artist, person, etc.) as well as listnav, the links element includes self and parent elements. The topnav includes a longer list which you can see in the tester. HATEOAS links in the body only contain self. HATEOAS links are required when mentioned below.

External Links

All external links are of the form of an array: "externallink":[{"url":"x","label":"y"}]. As noted these are typically html links, and may or may not be of any use to a json application. The externallinks element is always optional, and will not be included if there are no associated external links. The label may contain an HTML "i" tag.

Detailed JSON Documentation by head.type

art

API responses with head.type == 'art' include the following elements in the body. These same elements are found in the "art" array in the body of the other listed responses. Objects in an art array also include a top level HATEOAS links element (e.g. body.art[1].links).

artist

In addition to the required "self" and "parent", the HATEOAS links for artist can include "ref":"asperson" where the database contains both art that is by the artist (listed in this response) and art that refers to the artist (listed in the asperson link). In addition to the art array, the body member of a response with head type "artist" includes:

person

In addition to the required "self" and "parent", the HATEOAS links for person can include "ref":"asartist" where the database contains both art that is by the artist (listed in the asartist link) and art that refers to the artist (listed in this response). In addition to the art array, the body member of a response with head type "person" includes the following members:

landmark

In addition to the art array, the body member of a response with head type "landmark" includes the following members:

content

in addition to the art array, the body member of a response with head type "content" includes the optional string comments, which may contain the HTML tags "b", "i", and "br". Double quotes are escaped in the JSON, ASCII line breaks are converted to spaces.

tour

The location member of the art array in the body of a response with head type "tour" can include the additional member tourmapoverride, an object with the required strings "latitude" and longitude" (e.g.. body.art[x].location.tourmapoverride.latitude). This member is present when the art in question is best viewed from a distance, and it can be used to position a different numbered point on a map of the tour. In addition to the art array, the body includes the following members:

exhibit

The body member of a response with a head type "exhibit" can include either an art array or sections, which is an array of objects with two members: name (an optional string) and an art array. The web site and the tester display these exhibit results with the name of each section over the associated art list. See for example the "War" exhibit.

In addition to the art or sections array, the body member includes the following members:

Using geo.json

The philart.net/api/geo.json request takes two required URL arguments, ll and bb. The topnav entry for geo includes the sample arguments ll=39.952400,-75.165700&bb=39.951400,-75.166700,39.953400,-75.164700. ll stands for "latitude, longitude," and is used to sequence the array of returned art descriptions. bb stands for "bounding box" and is used to determine which pieces of art will be returned, where the first two values are the minimum latitude and longitude, and the last two values are the maximum latitude and longitude. All three latitude values and all three longitude values in the two arguments must conform to the following restrictions, or the API will return a 400 error:

All art returned will have a latitude and longitude within the range specified by the bb argument. If no art is found within the specified range, the API will return a 404.

All art returned will be sequenced by distance from the ll argument, where distance is defined as the delta of latitude plus the delta of longitude. While this is not mathematically correct, it requires a minimum of calculation and is close enough in an environment where an approximately NSEW street grid confines most travel.

If your application is driven by a map api that specifies a bounding box, you should use the bounding box coordinates supplied by the map api. However, you should not call this API if the bounding box is completely outside the valid range. If the source bounding box overlaps the valid bounding box values you should adjust the bounding box arguments to match the overlapping portion. If the bounding box is within range, but you are getting the ll based on current geolocation of the device, you should adjust the ll to the nearest valid point.

If your application is driving a map api that accepts a bounding box argument, you should use the same bounding box for both, though as in the previous case you may need to adjust the arguments or skip calling the API altogether.

If your application is driving a map api that does not accept a bounding box argument then you will need to guess a bounding box based on the zoom size you are requesting, which will probably vary across map APIs and devices.

If you are building an application that is going to show information about the very nearest art, without using a map, you should try using a very small bounding box, for example +- .0001 from both parts of the ll.

Error Returns

If your request is not recognized as an API request you will receive a normal philart.net web site response, probably the standard 404 page.

The following JSON objects may be attached to a status 500, 400 or 404 by the API. Anything other than 200 should be considered an error. The format was copied from the Twitter specification, though this API never returns more than one error in the array.

The API Tester

Everything between this paragraph and the footer tag in "view source" constitutes the API tester, which functions as follows:

Test Navigation Requests

Test Numeric ID Requests

Test the Geolocation Request