Was this helpful?
The Alpaca Travel GraphQL API allows developers to build curated lists and full trip itineraries for travel. The integration with OpenStreetMap (OSM) allows developers to search and plot places on to their itineraries, and access information such as opening hours, address, and more from the OSM database. Additionally, Alpaca links information from OSM to Wikidata and MediaWiki, providing access to broader information about the place, such as photos and official websites, population statistics, and more.
In this technical guide, we will provide information to developers building apps or websites on top of the Alpaca API, to help them leverage the OSM integration. We will cover topics such as:
OpenStreetMap (OSM) is a collaborative project that creates and provides free geographic data and map images to anyone who wants them. It is a community-driven project that allows users to contribute, edit, and use map data. The data is collected and maintained by a community of volunteers, who map the world using GPS devices, aerial imagery, and other sources.
OSM provides a wide range of data that can be used for various purposes, such as:
OSM data is available under an open license, which allows for free use and distribution, even for commercial purposes. This makes it a popular choice for a wide range of applications, from small hobby projects to large-scale enterprise solutions. With OSM, developers can access a wealth of geographic data to build powerful and informative applications.
OpenStreetMap (OSM) uses three main types of objects inside its database: nodes, ways, and relations. Nodes represent a single location, while relations can define a number of objects, such as a city or a building. Sometimes a node is a label for the broader relation, such as the node representing the label for "Melbourne", but it is part of a relation that contains more information, such as the Wikidata, bounds for maps, etc.
In OSM, identifiers are presented in the format "type" + "ID", for example "N123" for a node or "R123" for a relation.
place/openstreetmap:<osmtype>:<osmid>
| OpenStreetMap ID | Alpaca Place ID |
|---|---|
| Type: Node, ID: 21579127 | place/openstreetmap:node:21579127 |
| Type: Relation, ID: 4246124 | place/openstreetmap:relation:4246124 |
To reference a node or relation in the Alpaca Travel GraphQL API, the format is "place/openstreetmap:" + "osmtype" (node, relation, way) + ":" + "osmid". For example, to reference a node with ID 123 in OSM, the identifier in Alpaca would be "place/openstreetmap:node:123", and for a relation with ID 123, the identifier would be "place/openstreetmap:relation:123".
It is important to note that when referencing a node or relation in Alpaca, the "osmtype" and "osmid" must be separated by a colon (:), and the identifier must start with "place/openstreetmap:".
To identify the OSM ID's from Nominatim or other search platforms, you can use the Overpass API, which allows to extract information from the OpenStreetMap database. You can also use the Nominatim service that is provided by OpenStreetMap, which you can search for a place and get the OSM ID.
In summary, to reference a place in the Alpaca API, developers need to use the OSM identifier in the format "place/openstreetmap:osmtype:osmid". You can use the Overpass API or Nominatim to find the OSM identifier for a place.
1query GetPlace {
2 place(id: "place/openstreetmap:node:21579127") {
3 name
4
5 # Access the label
6 position {
7 lon
8 lat
9 }
10
11 # Access the bounds for the place
12 bounds {
13 w
14 s
15 e
16 n
17 }
18 }
19}Sandbox: Configure | Try Operation
1{
2 "data": {
3 "place": {
4 "name": "Melbourne",
5 "position": {
6 "lon": 144.9631608,
7 "lat": -37.8142176
8 },
9 "bounds": {
10 "w": 144.44405,
11 "s": -38.49937,
12 "e": 146.1925,
13 "n": -37.40175
14 }
15 }
16 }
17}To help developers work with place information from OSM more efficiently, Alpaca offers additional functionality. One of these features is the ability to resolve multiple references of a relation and node that potentially reference the same place. This is useful because, in OSM, a place can be represented by both a node (a single location) and a relation (a broader object that contains multiple locations).
For example, a node might represent the label for "Melbourne", but it is part of a relation that contains more information, such as the Wikidata, bounds for maps, etc. Alpaca allows developers to access the broader 'bounds' of the parent relation, but use the position of the label. This can be useful for plotting places on a map or for providing more accurate location-based information.
To take advantage of this functionality, developers can reference the place in the Alpaca API using the "place/openstreetmap:osmtype:osmid" format, as explained in the previous section. Alpaca will automatically resolve the information and return the most accurate and relevant information for the place.
Additionally, Alpaca allows you to access broader information about the place, such as photos and population statistics. Furthermore, it links information from OSM to Wikidata and MediaWiki, providing access to broader information about the place. This is useful for accessing photos of towns, or information about population etc.
In summary, Alpaca offers additional functionality to assist working with place information from OSM, such as resolving multiple references of a relation and node to return the most accurate and relevant information, and linking information from OSM to Wikidata and MediaWiki, to provide developers with more context and information about the place.
1query GetPlace {
2 place(id: "place/openstreetmap:node:21579127") {
3 name
4
5 # Translated names
6 nameAR: attrValue(id: "place/name", locale: "ar")
7
8 # Offical websites
9 websiteUrl
10
11 # Access some deeper information
12 population: attrValue(id: "place/population")
13 wikidata: attrValue(id: "place/wikipedia-url", locale: "en")
14
15 # Mapping data
16 position {
17 lon
18 lat
19 }
20 bounds {
21 w
22 s
23 e
24 n
25 }
26
27 # Images
28 images: mediaContainers(first: 3) {
29 nodes {
30 resource {
31 ... on MediaImage {
32 url(bestFit: [200, 200])
33 copyright
34 attribution
35 caption
36 }
37 }
38 }
39 }
40
41 # Source and Attribution
42 contributor
43 }
44}Sandbox: Configure | Try Operation
1{
2 "data": {
3 "place": {
4 "name": "Melbourne",
5 "nameAR": "ملبورن",
6 "websiteUrl": "https://www.melbourne.vic.gov.au/Pages/home.aspx",
7 "population": 4347955,
8 "wikidata": "https://en.wikipedia.org/wiki/Melbourne",
9 "position": {
10 "lon": 144.9631608,
11 "lat": -37.8142176
12 },
13 "bounds": {
14 "w": 144.44405,
15 "s": -38.49937,
16 "e": 146.1925,
17 "n": -37.40175
18 },
19 "images": {
20 "nodes": [
21 ...
22 ]
23 },
24 "contributor": "OpenStreetMap"
25 }
26 }
27}Wikidata is a free and open-source knowledge base that can be read and edited by both humans and machines. It is a collaborative project run by the Wikimedia Foundation and is closely connected to Wikipedia. Wikidata stores structured data and can be used to provide additional information, such as translations and relationships between different pieces of information.
For places and locations, Wikidata provides a wealth of information, such as:
All this information is linked to the corresponding Wikipedia articles and other sources of information to make it as accurate as possible. Wikidata allows developers to access a large amount of information about a place in a structured and consistent manner.
You can also find all the attributes that are available for a location with the following query:
1query {
2 place(id: "place/openstreetmap:relation:4246124") {
3 id
4
5 # Load the first 100 attributes for the product
6 attrs(first: 100) {
7 edges {
8 node {
9 id
10 value
11 }
12 }
13 }
14 }
15}Sandbox: Configure | Try Operation
MediaWiki is an open-source software that is used to power Wikipedia and other Wikimedia projects. It is a powerful and flexible platform for creating and managing wikis, which are websites that allow users to easily create and edit web pages. MediaWiki is used to store and organize large amounts of information, including text, images, videos, and other media.
One of the features of MediaWiki is the ability to upload and organize images and other media. Alpaca Travel API leverages this feature by providing links to photos from MediaWiki for the places in your itinerary. This allows developers to access a wide variety of high-quality photos of the places they are interested in, which can be used to enhance the user experience and provide more information about the place. The photos can be used for different purposes, such as creating visual itineraries, displaying photos on maps, and more.
Where possible, Alpaca have mapped OpenStreetMap places against the CC0 Creative Commons Attribution icons offered by Mapbox called Maki.
Maki is an icon set made for map designers. Maki includes icons for common points of interest like parks, museums, and places of worship. Each icon is available as a 15px by 15px SVG file. Maki is open source and CC0 licensed
This makes it easy to style and present places of interest that are added to your Alpaca itinerary and a wide range of icons that can be used with information from OSM.
1query GetPlaceMaki($placeId: ID!) {
2 place(id: $placeId) {
3 id
4 position {
5 lon
6 lat
7 }
8 maki
9 }
10}Sandbox: Configure | Try Operation
Alpaca offers a additional attributes that can be used to enhance the data available about a location.
1query GetPlace {
2 place(id: "place/openstreetmap:node:21579127") {
3 position {
4 lon
5 lat
6
7 # Access the timezone at the coordinate
8 timezone: attrValue(id: "place/time-zone")
9 # Access the currency for the country
10 currency: attrValue(id: "place/country-currency")
11
12 # Further information, such as regions..
13 iso3166: attrValue(id: "place/iso-3166-2")
14
15 # Australian information, such as locality, gov, etc
16 locality: attrValue(id: "place/abs:locality")
17 lga: attrValue(id: "place/abs:local-government-area")
18 electoral: attrValue(id: "place/abs:commonwealth-electoral-division")
19 tourismRegion: attrValue(id: "place/abs:tourism-region")
20 }
21 }
22}Sandbox: Configure | Try Operation
The response if successful will look like the following:
1{
2 "data": {
3 "place": {
4 "position": {
5 "lon": 144.9631608,
6 "lat": -37.8142176,
7 "timezone": "UTC+10:00",
8 "currency": {
9 "code": "AUD",
10 "num": 36,
11 "minor": 2,
12 "name": "Australian dollar",
13 "symbols": [
14 "A$",
15 "A＄",
16 "＄",
17 "$",
18 "dollar",
19 "dollars",
20 "Dollar",
21 "Dollars",
22 "A﹩",
23 "﹩"
24 ]
25 },
26 "iso3166": "AU-VIC",
27 "locality": "Melbourne",
28 "lga": "Melbourne (C)",
29 "electoral": "Melbourne (Northern Metropolitan)",
30 "tourismRegion": "Melbourne"
31 }
32 }
33 }
34}Where opening hours are available, you can use the Alpaca platform to interpret and display opening hours of locations.
Alpaca also offers the inclusion of Public Holidays in order to flag to users of your website or application that they may have affected operating hours due to local observed public holidays.
1# Obtain the open/closed hours for the place given a period, such as the
2# upcoming week or future date range. Includes information on local public
3# holidays that could affect opening hours.
4
5query QueryDateRangeOpenClosedTimes($placeId: ID!) {
6 # Use the place() operation
7 place(id: $placeId) {
8 # Access the opening hours (where specified)
9 hours {
10 # Use the forDays operation to obtain days across a range of dates. By
11 # default, without any arguments the next 7 days will be selected. You
12 # can change the range by specifying an alternative offset (which allows
13 # you to specify values like { days: 14 }) or provide a specific start and
14 # end dates (as ISO-8601 date strings)
15 forDays {
16 # Date/day, as ISO-8601, or as formatted for presentation using the
17 # Unicode Technical Standard #35 Date Field Symbols
18 date(format: "EEE, MMM d")
19 # Whether there is a public holiday for this date detected for this
20 # region on this date
21 publicHolidays
22 # Obtain the intervals for this date, requesting the opening status
23 # status is optional, otherwise use Open/Closed to specify your pref
24 intervals(status: Open) {
25 # Hours, from/to as ISO-8601 string, or formatted using the Unicode
26 # Technical Standard #35 Date Field Symbols
27 from(format: "h:mm a")
28 to(format: "h:mm a")
29 # Status (Open/Closed)
30 status
31 # Any corresponding comment for the opening hours
32 comment
33 }
34 }
35 }
36 }
37}Sandbox: Configure | Try Operation
1{
2 "data": {
3 "place": {
4 "hours": {
5 "forDays": [
6 {
7 "date": "Mon, Jan 23",
8 "publicHolidays": [],
9 "intervals": [
10 {
11 "from": "7:00 AM",
12 "to": "3:30 PM",
13 "status": "Open",
14 "comment": null
15 }
16 ]
17 },
18 {
19 "date": "Tue, Jan 24",
20 "publicHolidays": [],
21 "intervals": [
22 {
23 "from": "7:00 AM",
24 "to": "3:30 PM",
25 "status": "Open",
26 "comment": null
27 }
28 ]
29 },
30 {
31 "date": "Wed, Jan 25",
32 "publicHolidays": [],
33 "intervals": [
34 {
35 "from": "7:00 AM",
36 "to": "3:30 PM",
37 "status": "Open",
38 "comment": null
39 }
40 ]
41 },
42 {
43 "date": "Thu, Jan 26",
44 "publicHolidays": ["Australia Day"],
45 "intervals": [
46 {
47 "from": "7:00 AM",
48 "to": "3:30 PM",
49 "status": "Open",
50 "comment": null
51 }
52 ]
53 },
54 {
55 "date": "Fri, Jan 27",
56 "publicHolidays": [],
57 "intervals": [
58 {
59 "from": "7:00 AM",
60 "to": "3:30 PM",
61 "status": "Open",
62 "comment": null
63 }
64 ]
65 },
66 {
67 "date": "Sat, Jan 28",
68 "publicHolidays": [],
69 "intervals": [
70 {
71 "from": "8:00 AM",
72 "to": "3:30 PM",
73 "status": "Open",
74 "comment": null
75 }
76 ]
77 },
78 {
79 "date": "Sun, Jan 29",
80 "publicHolidays": [],
81 "intervals": [
82 {
83 "from": "9:00 AM",
84 "to": "3:30 PM",
85 "status": "Open",
86 "comment": null
87 }
88 ]
89 }
90 ]
91 }
92 }
93 }
94}OpenStretMap is a database that is distributed by many different providers. This provides you a number of options you can use for your application in order to enhance your search functionality.
The Alpaca API provides a search capability for searching places from OSM. This option allows you to provide a search option on your application or website.
1query {
2 placeAutocompleteSearch(first: 3, text: "Melbourne", sources: OpenStreetMap) {
3 edges {
4 # Can build single or multiple line responses
5 single {
6 label
7 matches {
8 length
9 offset
10 }
11 }
12
13 # The place information
14 node {
15 # Basic identifiers
16 id
17 name
18
19 # Location to show on a map
20 position {
21 lon
22 lat
23 }
24
25 # Context from adddress
26 address {
27 region
28 country
29 }
30 }
31 }
32 }
33}Sandbox: Configure | Try Operation
If successful, a response may look like the following:
1{
2 "data": {
3 "placeAutocompleteSearch": {
4 "edges": [
5 {
6 "single": {
7 "label": "Melbourne, Australia",
8 "matches": [
9 {
10 "length": 9,
11 "offset": 0
12 }
13 ]
14 },
15 "node": {
16 "id": "place/openstreetmap:relation:4246124",
17 "name": "Melbourne",
18 "position": {
19 "lon": 144.9631608,
20 "lat": -37.8142176
21 },
22 "address": {
23 "region": "Victoria",
24 "country": "Australia"
25 }
26 }
27 },
28 {
29 "single": {
30 "label": "Melbourne, United States",
31 "matches": [
32 {
33 "length": 9,
34 "offset": 0
35 }
36 ]
37 },
38 "node": {
39 "id": "place/openstreetmap:relation:117646",
40 "name": "Melbourne",
41 "position": {
42 "lon": -80.6371513,
43 "lat": 28.106471
44 },
45 "address": {
46 "region": "Florida",
47 "country": "United States"
48 }
49 }
50 },
51 {
52 "single": {
53 "label": "Melbourne, United States",
54 "matches": [
55 {
56 "length": 9,
57 "offset": 0
58 }
59 ]
60 },
61 "node": {
62 "id": "place/openstreetmap:relation:129273",
63 "name": "Melbourne",
64 "position": {
65 "lon": -93.1030319,
66 "lat": 41.9430186
67 },
68 "address": {
69 "region": "Iowa",
70 "country": "United States"
71 }
72 }
73 }
74 ]
75 }
76 }
77}Nominatim (from the Latin, 'by name') is a tool to search OSM data by name and address and to generate synthetic addresses of OSM points (reverse geocoding).
Nominatim is a search service offered by OpenStreetMap (OSM) that allows developers to search for places and addresses using free-text queries. It uses a geocoding algorithm to match the query with the most relevant place or address. It can return results in various formats, such as JSON, XML, and CSV.
To use Nominatim for searching for places from OSM, developers can send a HTTP GET request to the Nominatim API endpoint with the search query and other parameters, such as the format of the response, the limit of the number of results, the language, and more. The API will return a list of search results, each containing information such as the OSM ID, the type of the object (node, way, or relation), the name of the place, the address, the bounding box, and more.
It is recommended to use Nominatim API with care and to follow the usage policy to avoid overloading the service and get the best results. Also, it's recommended to cache results and use bounding box or viewbox parameters to limit the results to the area of interest.
Several search engines are available to be able to efficiently search for OpenStreetMap locations.
You can use these services which will allow you to locate your OpenStreetMap place identifiers and then can use these to add to your Alpaca itineraries.
Copyright © 2024 - Made with love ❤️ in Australia.