API Events Proposal
Here is the first proposal for the opensource API of the opendata database of all events of Marseille Provence 2013.
- events : Returns a collection of MP2013 events corresponding to search criteria
- near : Returns all events near a specific geo-position and from a specific date.
- id : Returns all events with only their name and id
- event : Returns all the details about an event searched by its id
Returns a collection of MP2013 events.
api.mp2013.fr/events?from=[Date]&to=[Date]&limit=[int]&offset=[int]&lang=fr|en&format=json
http://api.mp2013.fr/events?from=2013-01-01&to=2013-01-15&lang=fr&offset=10&limit=5&format=json
Returns the events defined from the given data. Date should be formatted as YYYY-MM-DD. If this parameter is left empty, the current date is used.
Example :
?from=2013-01-12
Returns events generated before the given date. Date should be formatted as YYYY-MM-DD. If this parameter is left empty then the function returns all events with no time limit.
Example :
?to=2013-09-01
Force the API to returns only the events with a specific language (fr or en).
Example :
?lang=fr
Use this parameter to limit your results to those that fall within a specified range. You can use it to show the first X number of results, or to show a range from X - Y results.
Defines the format of the result document, by default the format is rdf.
Example :
?format=json
Returns all events near a specific geo-position and from a specific date.
api.mp2013.com/near?longitude=[float]&latitude=[float]&from=[Date]&limit=[int]&offset=[int]&lang=fr|en&format=json
The latitude to search around. This parameter will be ignored unless it is inside the range -90.0 to +90.0 (North is positive) inclusive. It will also be ignored if there isn't a corresponding long parameter.
Example : 37.7821120598956
The longitude to search around. The valid ranges for longitude is -180.0 to +180.0 (East is positive) inclusive. This parameter will be ignored if outside that range, if it is not a number.
Example : -122.400612831116
Returns the events defined from the given data. Date should be formatted as YYYY-MM-DD. If this parameter is left empty, the current date is used.
Example :
?from=2013-01-12
Force the API to returns only the events with a specific language (fr or en).
Example :
?lang=fr
Use this parameter to limit your results to those that fall within a specified range. You can use it to show the first X number of results, or to show a range from X - Y results.
Defines the format of the result document, by default the format is rdf.
Example :
?format=json
##id
All the events with only their name and id. This function is more fast to create a list of all events. Use the event API to target a specific event with an id in this list.
http://api.mp2013.fr/id?format=rdf|json
Defines the format of the result document, by default the format is rdf.
Example :
?format=json
Access an event by its unique id
http://api.mp2013.fr/event?id=13EVT027367&format=json
The id of the event to return.
Defines the format of the result document, by default the format is rdf. The format property accept the rdf and json.
Example :
?format=json
Returns a list of all changes in the database (a new event, an event is disabled, an event is changed, etc.)
api.mp2013.com/history?order=DESC|ASC&limit=[int]&offset=[int]&format=json
Defines the order of the results by DESC or ASC. By default the result is by DESC.
Example :
?order=DESC
Use this parameter to limit your results to those that fall within a specified range. You can use it to show the first X number of results, or to show a range from X - Y results.
Defines the format of the result document, by default the format is rdf.
Example :
?format=json
Select in the next list all items to returns.
- 200 - OK : Success!
- 400 - Bad request
- 500 - Internal server error
- 502 - Bad Gateway : The API is down or being upgraded.
- 504 - Gateway timeout : The servers are up, but the request couldn't be serviced due to some failure within our stack. Try again later.
- 201 - Created
- 204 - No Content
- 401 - Unauthorized
- 403 - Forbiden
- 404 - Not found
- 405 - Method Not Allowed
- 406 - Not Acceptable : Returned by the Search API when an invalid format is specified in the request.
- 408 - Request Timeout
- 429 - Too Many Requests : Returned when a request cannot be served due to the application's rate limit having been exhausted for the resource.
{
"errors":
[
{ "code" : 34 , "message" : "Sorry, that page does not exist" }
]
}<?xml version="1.0" encoding="UTF-8"?>
<errors>
<error code="34">Sorry, that page does not exist</error>
</errors>In addition to descriptive error text, error messages contain machine-parseable codes. While the text for an error message may change, the codes will stay the same. The following table describes the custom codes which may appear when working with the API:
?? Defines it example :
- 10 : Invalid argument : The argument is not defined ?
[Creative Commons 3.0 BY-SA](http://creativecommons.org/licenses/by-sa/3.0/)