How to call the API

The API is REST-ful and operates over a standard HTTP GET protocol. The base URL is:

http://api.wikilocation.org/

The method is added onto the URL with additional parameters being provided via the querystring. There are two optional parameters which are available on all methods.

Note: It is highly recommended that you follow @WikiLocation on Twitter for updates on changes to the API, downtime notices, and new features.

Available Methods

articles

Find nearby Wikipedia articles based on a specific latitude and longitude

Parameters

  • lat (required) - latitude in decimal degree format.
  • lng (required) - longitude in decimal degree format.
  • radius (optional) - the radius (in metres) to search within. There is a maximum radius of 20km and it will default to 250m if no radius is supplied.
  • limit (optional) - the number of results you want to return. There is a maximum limit of 50 results although you can paginate (see below). This will default to 50 if no lower figure is sent.
  • offset (optional) - the offset from the first result returned. E.g. if you wanted to view results 51-100 you would supply an offset of 50. There is no maximum for this parameter. The default is 0.
  • type (optional) - the type of article you are interested in. There are various options for this so best to look at some results and then filter from there (e.g. you could filter by a type of "river" or "landmark"). The default is no filter.
  • title (optional) - does a partial word match on the title of the article. By default, all articles are returned.

Example Usage

Request:

http://api.wikilocation.org/articles?lat=51.500688&lng=-0.124411&limit=1

Response:
{
    "articles": [
        {
            "id": "7290308",
            "lat": "51.5006",
            "lng": "-0.124611",
            "title": "Big Ben",
            "url": "http:\/\/en.wikipedia.org\/w\/index.php?curid=7290308",
            "distance": "17m"
        }
    ]
}
Request:

http://api.wikilocation.org/articles?lat=51.500688&lng=-0.124411&limit=3&offset=5&format=xml&locale=de

Response:
<?xml version="1.0" encoding="utf-8"?>
<wikilocation>
    <articles>
        <article>
            <id>908869</id>
            <lat>51.5006</lat>
            <lng>-0.126667</lng>
            <type>landmark</type>
            <title>Parliament Square</title>
            <url>http://de.wikipedia.org/w/index.php?curid=908869</url>
            <distance>157m</distance>
        </article>
        <article>
            <id>1339639</id>
            <lat>51.5008</lat>
            <lng>-0.121667</lng>
            <type>landmark</type>
            <title>Westminster Bridge</title>
            <url>http://de.wikipedia.org/w/index.php?curid=1339639</url>
            <distance>191m</distance>
        </article>
        <article>
            <id>903392</id>
            <lat>51.5</lat>
            <lng>-0.126944</lng>
            <type>landmark</type>
            <title>St. Margaret¬ís Church</title>
            <url>http://de.wikipedia.org/w/index.php?curid=903392</url>
            <distance>191m</distance>
        </article>
    </articles>
</wikilocation>

gowalla/[ID] (deprecated)

Due to Gowalla closing down, this method will be unavailable after 1st Feb 2012. You are advised to use /articles with a valid lat/lng to find nearby articles or use the /foursquare method.

Find Wikipedia articles based on a Gowalla spot ID. The spot ID can be found by going to the spot on the Gowalla website (e.g. http://gowalla.com/spots/22087) and then taking the digits from the end of the URL (in this case "22087").

This method will return not only an "articles" array (which lists the Wikipedia entries along with their distance from the Gowalla spot) but also a "spot" array giving some basic details from Gowalla such as lat/lng, name, and the radius.

Parameters

  • exact (optional) - defaults to false. If set to true, it will only return articles with the exact same name as the Gowalla spot (e.g. the spot for "Big Ben" returns two articles - specifying "exact" ensures that only an article with the title "Big Ben" is returned). This method is useful as some Gowalla venues may be incorrectly placed by a small distance meaning that simply taking the first result as the article for that location may not be correct. Be advised that "exact" works by matching the titles so if they are not exact then it will not work (e.g. "St David's Station" and "St Davids Station" would not match).

Note: This method is provided as a quick convenience to show the nearest articles to a Gowalla spot and as such you can not specify a limit or an offset or override the radius that Gowalla provides for the spot. To use these features, you are recommended to manually take the lat/lng using the Gowalla API and then use the articles method above.

Example Usage

Request:

http://api.wikilocation.org/gowalla/22087

Response:
{
    "spot": {
        "lat": 51.500758717,
        "lng": -0.1245939732,
        "radius": "50m",
        "name": "Big Ben"
    },
    "articles": [
        {
            "id": "7290308",
            "lat": "51.5006",
            "lng": "-0.124611",
            "title": "Big Ben",
            "url": "http:\/\/en.wikipedia.org\/w\/index.php?curid=7290308",
            "distance": "18m"
        },
        {
            "id": "354633",
            "lat": "51.501",
            "lng": "-0.125",
            "title": "Westminster tube station",
            "url": "http:\/\/en.wikipedia.org\/w\/index.php?curid=354633",
            "distance": "39m"
        }
    ]
}

foursquare/[ID]

Find Wikipedia articles based on a Foursquare venue ID. The venue ID can be found by going to the spot on the Foursquare website (e.g. http://foursquare.com/venue/141395) and then taking the digits from the end of the URL (in this case "141395").

This method will return not only an "articles" array (which lists the Wikipedia entries along with their distance from the Foursquare venue) but also a "venue" array giving some basic details from Foursquare such as lat/lng and name. The radius will be either the default of 250m or the radius you defined as a parameter (as Foursquare venues do not have a radius specified as Gowalla spots do).

Parameters

  • radius (optional) - the radius (in metres) to search within. There is a maximum radius of 5km and it will default to 250m if no radius is supplied.
  • exact (optional) - defaults to false. If set to true, it will only return articles with the exact same name as the Foursquare venue (e.g. the spot for "Big Ben" with a radius of 250m returns several articles - specifying "exact" ensures that only an article with the title "Big Ben" is returned). This method is useful as some Foursquare venues may be incorrectly placed by a small distance meaning that simply taking the first result as the article for that location may not be correct. Be advised that "exact" works by matching the titles so if they are not exact then it will not work (e.g. "St David's Station" and "St Davids Station" would not match).

Note: This method is provided as a quick convenience to show the nearest articles to a Foursquare venue and as such you can not specify a limit or an offset. To use these features, you are recommended to manually take the lat/lng using the Foursquare API and then use the articles method above.

Example Usage

Request:

http://api.wikilocation.org/foursquare/141395?radius=50

Response:
{
    "venue": {
        "lat": 51.500595,
        "lng": -0.124648,
        "radius": "50m",
        "name": "Big Ben"
    },
    "articles": [
        {
            "id": "7290308",
            "lat": "51.5006",
            "lng": "-0.124611",
            "title": "Big Ben",
            "url": "http:\/\/en.wikipedia.org\/w\/index.php?curid=7290308",
            "distance": "3m"
        }
    ]
}

woeid/[ID]

Find Wikipedia articles based on a Yahoo! WOEID. A WOEID is a unique, non-repetitive identifier for any geolocational object from a famous landmark to a continent.

This method will return not only an "articles" array (which lists the Wikipedia entries along with their distance from the "centroid") but also a "woeid" array giving some basic details from Yahoo! such as lat/lng and name. The radius will be either the default of 250m or the radius you defined as a parameter (as the scale of some of the WOEIDs makes an automated algorithm for determining size redundant).

Parameters

  • radius (optional) - the radius (in metres) to search within. There is a maximum radius of 5km and it will default to 250m if no radius is supplied.
  • exact (optional) - defaults to false. If set to true, it will only return articles with the exact same name as the WOEID name (e.g. the WOEID for "Big Ben" with a radius of 250m returns several articles - specifying "exact" ensures that only an article with the title "Big Ben" is returned). Whilst WOEIDs tend to be well-maintained and accurate, there could be several articles in the vicinity and depending on the accuracy of the lat/lng on the article, the first result may not always be the one you wanted. Be advised that "exact" works by matching the titles so if they are not exact then it will not work (e.g. "St David's Station" and "St Davids Station" would not match).

Note: This method is provided as a quick convenience to show the nearest articles within the centroid of a WOEID resultset and as such you can not specify a limit or an offset. To use these features, you are recommended to manually take the lat/lng using the Yahoo! GeoPlanet API and then use the articles method above.

Example Usage

Request:

http://api.wikilocation.org/woeid/22474116?exact=true

Response:
{
    "woeid": {
        "lat": 51.500599,
        "lng": -0.12461,
        "radius": "250m",
        "name": "Big Ben"
    },
    "articles": [
        {
            "id": "7290308",
            "lat": "51.5006",
            "lng": "-0.124611",
            "title": "Big Ben",
            "url": "http:\/\/en.wikipedia.org\/w\/index.php?curid=7290308",
            "distance": "1m"
        }
    ]
}

Error Handling

When an error is encountered, you will be sent an error response in the format that you made your initial request for (defaults to 'json'). The error output will consist of an error element with a single message:

Example

Request:

http://api.wikilocation.org/foursquare

Response:
{"error":"You must supply a FourSquare venue ID e.g. http:\/\/api.wikilocation.org\/foursquare\/141395"}

It is recommended that you always check for the presence of an error element before dealing with other elements. There will never be an error element if the request was successful.

Caching & Throttling

At present, this API is not in any way throttled meaning you can make multiple requests to the service. However, it should be noted that you are recommended to cache any responses from the API in order to save my bandwidth!

It is suggested that you make API calls no more frequently than once a second - if you are building a large application, please let me know so I can cater for more bandwidth.

If I deem that your application is making too many requests, then I reserve the right to throttle your requests. If you set your user-agent to something identifiable (preferably with an email address or URL in it) then I will contact you before throttling.

Please contact me if you have any questions.

Compression

All responses are compressed using GZIP to maximise transfer speed.

Flash

Whilst I feel that Flash as a programming language is finally coming to the end of its tenure, I know there are still Flash developers out there who want to make cool stuff with this API. Therefore, there is a crossdomain.xml file installed in the API root so that you can make connections from any location.

Stats

I keep a log of all API requests so I can provide statistics to developers of their API usage. If you would like a breakdown of your API requests, then please send me your base user agent and I can give you a list of the number of requests per day broken down by application version. This is particularly useful for mobile developers who want to see if their users have migrated to a new version.

Licensing

This API is released for free (although donations are always appreciated especially if the API is being used for commercial purposes) under the Creative Commons Attribution 3.0 Unported license - please include an attribution link to either wikilocation.org or to bendodson.com in any application you build using this service. You can also let me know what you're working on as it is always interesting to see how the API is used.

Locales

At present, the following locales are supported via the WikiLocation API:

You can download a MySQL dump of all of the entries for each locale by choosing the "mysqldump" links above. These are automatically generated at 6am UTC every Friday.