Skip to content

cedarmaps-sdk-android-public
cedarmaps-sdk-android-public
Commit 36652fa4 authored by Deployer's avatar Deployer
Browse files
Options

Updated README

parent 346a4a16
Show whitespace changes
Inline Side-by-side
Showing with 84 additions and 314 deletions
.gitignore
View file @ 36652fa4
...@@ -6,3 +6,4 @@ ...@@ -6,3 +6,4 @@
/.idea/libraries /.idea/libraries
.DS_Store .DS_Store
/build /build
*.apk
CedarMapsSampleApp/src/main/res/layout/fragment_map.xml
View file @ 36652fa4
...@@ -9,8 +9,8 @@ ...@@ -9,8 +9,8 @@
<com.cedarstudios.cedarmapssdk.MapView <com.cedarstudios.cedarmapssdk.MapView
android:id="@+id/mapView" android:id="@+id/mapView"
android:layout_width="fill_parent" android:layout_width="match_parent"
android:layout_height="fill_parent" android:layout_height="match_parent"
mapbox:mapbox_cameraZoom="14" mapbox:mapbox_cameraZoom="14"
/> />
......
README.md
View file @ 36652fa4
## Getting started with the CedarMaps Android SDK ## Getting Started with the CedarMaps Android SDK
This guide will take you through the process of adding a map to your Android app. This guide will take you through the process of adding a map to your Android app.
...@@ -16,7 +16,7 @@ repositories { ...@@ -16,7 +16,7 @@ repositories {
} }
dependencies { dependencies {
compile('com.cedarmaps:CedarMapsSDK:1.0.1@aar') { compile('com.cedarmaps:CedarMapsSDK:2.0.0@aar') {
transitive = true transitive = true
} }
} }
...@@ -45,24 +45,17 @@ If your App needs to access location services, it'll also need the following per ...@@ -45,24 +45,17 @@ If your App needs to access location services, it'll also need the following per
CedarMaps requires the following dangerous permissions: CedarMaps requires the following dangerous permissions:
`WRITE_EXTERNAL_STORAGE`, `ACCESS_COARSE_LOCATION` and `ACCESS_FINE_LOCATION`. `WRITE_EXTERNAL_STORAGE`, `ACCESS_COARSE_LOCATION` and `ACCESS_FINE_LOCATION`.
### Getting Access Token ### Configuring CedarMaps
In order to use CedarMaps API and TileSource you should get `AccessToken` with your client id and In order to use CedarMaps API, you should set your clientID, clientSecret and a context in your application.
client secret:
```java ```java
com.cedarstudios.cedarmapssdk.config.Configuration CedarMaps.getInstance()
configuration = new ConfigurationBuilder() .setClientID("YOUR_CLIENT_ID")
.setClientId(clientId) .setClientSecret("YOUR_CLIENT_SECRET")
.setClientSecret(clientSecret) .setContext(CONTEXT)
.build();
CedarMapsFactory factory = new CedarMapsFactory(configuration);
CedarMaps cedarMaps = factory.getInstance();
OAuth2Token oAuth2Token = cedarMaps.getOAuth2Token();
``` ```
Then you should use `oAuth2Token.getAccessToken()` in mapView or API
### The MapView ### The MapView
...@@ -71,362 +64,138 @@ like any other `ViewGroup` and its behavior can be changed statically with an ...@@ -71,362 +64,138 @@ like any other `ViewGroup` and its behavior can be changed statically with an
[XML layout](http://developer.android.com/guide/topics/ui/declaring-layout.html) [XML layout](http://developer.android.com/guide/topics/ui/declaring-layout.html)
file, or programmatically during runtime. file, or programmatically during runtime.
If you want to use MapView, first call this before using any `MapView`.
```java
CedarMaps.getInstance().prepareTiles(new OnTilesConfigured() {
@Override
public void onSuccess() {
}
@Override
public void onFailure(@NonNull String error) {
}
});
```
#### XML layout #### XML layout
To add the `MapView` as a layout element, add the following to your xml file: To add the CedarMaps `MapView` as a layout element, add the following to your xml file:
```xml ```xml
<com.cedarstudios.cedarmapssdk.view.MapView <com.cedarstudios.cedarmapssdk.MapView
android:id="@+id/mapView" android:id="@+id/mapView"
android:layout_width="match_parent" android:layout_width="match_parent"
android:layout_height="match_parent" /> android:layout_height="match_parent"
mapbox:mapbox_cameraZoom="14"
...
/>
``` ```
And then you can call it programmatically with And then you can call it programmatically with
```java ```java
MapView mapView = (MapView) findViewById(R.id.mapview); mMapView = (MapView) view.findViewById(R.id.mapView);
final CedarMapsTileSourceInfo cedarMapsTileSourceInfo = new CedarMapsTileSourceInfo(getContext(), configuration);
cedarMapsTileSourceInfo.setTileLayerListener(new CedarMapsTileLayerListener() { mMapView.getMapAsync(new OnMapReadyCallback() {
@Override @Override
public void onPrepared(CedarMapsTileSourceInfo tileLayer) { public void onMapReady(MapboxMap mapboxMap) {
mMapboxMap = mapboxMap;
mMapboxMap.setMaxZoomPreference(17);
mMapboxMap.setMinZoomPreference(6);
CedarMapsTileSource cedarMapsTileSource = new CedarMapsTileSource(tileLayer); MapboxMap.OnMapClickListener() {
CedarMapTileProvider provider = new CedarMapTileProvider(getContext(), cedarMapsTileSource); @Override
mapView.setTileProvider(provider); public void onMapClick(@NonNull LatLng latLng) {
mapView.getController().setZoom(12);
mapView.getController().setCenter(new GeoPoint(35.6961, 51.4231)); // center of Tehran
} }
}); });
}
});
``` ```
#### Changing API Base Url #### Changing API Base Url
You can change API Base Url by setting it on configuration object: You can change API Base Url by setting it on CedarMaps shared object:
```java ```java
MapView mapView = new MapView(context); CedarMaps.getInstance()
Configuration configuration = new ConfigurationBuilder() .setAPIBaseURL("YOUR_API_BASE_URL")
.setAPIBaseURL(CUSTOM_API_URL)
.setClientId(Constants.CLIENT_ID)
.setClientSecret(Constants.CLIENT_SECRET)
.setMapId(Constants.MAPID_CEDARMAPS_STREETS)
.build();
``` ```
CedarMaps SDK is based on [OpenStreetMap Android SDK v5.2](https://github.com/osmdroid/osmdroid) and provides `CedarMapsTileSource` and extra API over OpenStreetMap. CedarMaps SDK is based on [Mapbox GL Android SDK v5.1.4](https://github.com/mapbox/mapbox-gl-native) and provides `CedarMaps` and extra API over Mapbox.
For more information about how to use MapView and other components please see [OpenStreetMap Wiki](https://github.com/osmdroid/osmdroid/wiki) For more information about how to use MapView and other components please see [Mapbox Getting Started](https://www.mapbox.com/help/first-steps-android-sdk/)
### Attention
currently CedarMaps supports Tehran city.
======= =======
### CedarMaps API ### CedarMaps API
In addition to use MapView, you can use CedarMaps API to retrieve location based data and street search. In addition to use MapView, you can use CedarMaps API to retrieve location based data and street search.
Before beginning to call CedarMaps API you should get `AccessToken` with your client id and client secret
```java
com.cedarstudios.cedarmapssdk.config.Configuration
configuration = new ConfigurationBuilder()
.setClientId(clientId)
.setClientSecret(clientSecret)
.build();
CedarMapsFactory factory = new CedarMapsFactory(configuration);
CedarMaps cedarMaps = factory.getInstance();
OAuth2Token oAuth2Token = cedarMaps.getOAuth2Token();
```
Then you should use `oAuth2Token` with each API call
#### Geocode (Place Search) #### Geocode (Place Search)
For finding a street you can easily call streetSearch method. For finding a street you can easily call ```forwardGeocode``` methods.
```java ```java
Configuration configuration = new ConfigurationBuilder() CedarMaps.getInstance().forwardGeocode(query, new ForwardGeocodeResultsListener() {
.setOAuth2AccessToken(oAuth2Token.getAccessToken()) @Override
.setOAuth2TokenType(oAuth2Token.getTokenType()) public void onSuccess(@NonNull List<ForwardGeocode> results) {
.setMapId(Constants.MAPID_CEDARMAPS_STREETS)
.build();
CedarMaps cedarMaps = new CedarMapsFactory(configuration).getInstance();
searchResult = cedarMaps.geocode(searchTerm);
```
The output would be something like this for search term "همت":
```json
{
"results": [
{
"address": "اراضی عباس آباد,مهران,سید خندان,...",
"components": {
"city": "تهران",
"country": "ایران",
"districts": [
"منطقه 4",
"منطقه 3"
],
"localities": [
"اراضی عباس آباد",
"مهران",
"سید خندان",
"پاسداران"
],
"province": "تهران"
},
"id": 429874,
"location": {
"bb": {
"ne": "35.756689799999997,51.464761500000002",
"sw": "35.7491463,51.423702800000001"
},
"center": "35.749155599171999,51.428327751596903"
},
"name": "همت",
"type": "expressway"
},
{
"address": "المهدی",
"components": {
"city": "تهران",
"country": "ایران",
"districts": [
"منطقه 5"
],
"localities": [
"المهدی"
],
"province": "تهران"
},
"id": 338756,
"location": {
"bb": {
"ne": "35.770861600000003,51.323841700000003",
"sw": "35.770540400000002,51.323066400000002"
},
"center": "35.770585227006897,51.323426168064202"
},
"name": "همت",
"type": "street"
} }
], }
"status": "OK"
}
```
More advanced street searches are available in sample app;
#### Reverse Geocode
You can retrieve data about a location by using reverse geocode API
```java @Override
Configuration configuration = new ConfigurationBuilder() public void onFailure(@NonNull String errorMessage) {
.setOAuth2AccessToken(oAuth2Token.getAccessToken())
.setOAuth2TokenType(oAuth2Token.getTokenType())
.build();
CedarMaps cedarMaps = new CedarMapsFactory(configuration).getInstance();
searchResult = cedarMaps.geocode(lat, lng);
```
The output would be something like this for 35.716482704636825, 51.40897750854492:
```json
{
"result": {
"address": "بن بست سروش - زرتشت",
"city": "تهران",
"components": [
{
"long_name": "بن بست سروش",
"short_name": "بن بست سروش",
"type": "residential"
},
{
"long_name": "زرتشت",
"short_name": "زرتشت",
"type": "primary"
},
{
"long_name": "بهجت آباد",
"short_name": "بهجت آباد",
"type": "locality"
},
{
"long_name": "تهران",
"short_name": "تهران",
"type": "city"
} }
], });
"locality": "بهجت آباد",
"traffic_zone": {
"in_central": true,
"in_evenodd": true,
"name": "محدوده طرح ترافیک"
}
},
"status": "OK"
}
``` ```
#### Distance More advanced street searches are available in sample app;
This method calculates the distance between points in meters. It can be called with up to 50 different points in a single request. #### Reverse Geocode
The only supported profile is cedarmaps.driving which calculates the distance using car routing. You can retrieve data about a location by using Reverse Geocode API
```java ```java
Configuration configuration = new ConfigurationBuilder() CedarMaps.getInstance().reverseGeocode(
.setOAuth2AccessToken(oAuth2Token.getAccessToken()) coordinate,
.setOAuth2TokenType(oAuth2Token.getTokenType()) new ReverseGeocodeResultListener() {
.setMapId(Constants.MAPID_CEDARMAPS_DRIVING) @Override
.build(); public void onSuccess(@NonNull ReverseGeocode result) {
CedarMaps cedarMaps = new CedarMapsFactory(configuration).getInstance();
searchResult = cedarMaps.distance(new LatLng(35.6961, 51.4231), new LatLng(35.744625, 51.374600));
```
Response elements:
distance: The overall distance of the route, in meter
time: The overall time of the route, in ms
bbox: The bounding box of the route, format: minLon, minLat, maxLon, maxLat
}
The output would be something like this: @Override
public void onFailure(@NonNull String errorMessage) {
```json
{
"result": {
"routes": [
{
"bbox": [
51.368587,
35.74982,
51.41652,
35.762383
],
"distance": 7516.338,
"time": 500912
} }
] });
},
"status": "OK"
}
``` ```
#### Direction
#### Locality This method calculates the distance between points in meters. It can be called with up to 15 different points in a single request.
It gives you all localities in a city wih geometry in GeoJSON format. This API call needs a valid access token.
```java ```java
Configuration configuration = new ConfigurationBuilder() CedarMaps.getInstance().direction(departure, destination,
.setOAuth2AccessToken(oAuth2Token.getAccessToken()) new GeoRoutingResultListener() {
.setOAuth2TokenType(oAuth2Token.getTokenType()) @Override
.build(); public void onSuccess(@NonNull GeoRouting result) {
CedarMaps cedarMaps = new CedarMapsFactory(configuration).getInstance(); }
searchResult = cedarMaps.locality("tehran");
``` @Override
public void onFailure(@NonNull String error) {
Supported cities are: tehran, تهران
The output would be something like this:
```json
{
"results":
[
{
"geometry": {
"coordinates": [
[
[
51.3904371,
35.6144373
],
[
51.3860088,
35.6143914
],
[
51.3896979,
35.6169901
],
[
51.3893829,
35.6216496
],
[
51.3869264,
35.622008
],
[
51.3863595,
35.6257456
],
[
51.384092,
35.6256944
],
[
51.38384,
35.6281007
],
[
51.3821393,
35.6281007
],
[
51.378927,
35.6348585
],
[
51.378602,
35.6384921
],
[
51.3822129,
35.6370245
],
[
51.385588,
35.637117
],
[
51.3859658,
35.6313776
],
[
51.3916527,
35.6247423
],
[
51.3904371,
35.6144373
]
]
],
"type": "Polygon"
},
"name": "اسفندیاری و بستان"
} }
], });
"status": "OK"
}
``` ```
### More Examples Via TestApp ### More Examples Via Sample App
The CedarMaps Android SDK is actually an [Android Library Module](https://developer.android.com/tools/projects/index.html#LibraryModules), The CedarMaps Android SDK is actually an [Android Library Module](https://developer.android.com/tools/projects/index.html#LibraryModules),
which means in order to test it out in an emulator or a device during development a [Test Module](https://developer.android.com/tools/projects/index.html#testing) is needed. We call this test module which means in order to test it out in an emulator or a device during development a [Test Module](https://developer.android.com/tools/projects/index.html#testing) is needed. We call this test module
the **TestApp**. It contains many different examples of new functionality or just ways to do certain things. We highly recommend checking it out. the **SampleApp**. It contains many different examples of new functionality or just ways to do certain things. We highly recommend checking it out.
The source code for these tests / examples is located under the CedarMapsTestApp directory.
You can find more useful examples on [OpenStreetMap SDK Test App](https://github.com/osmdroid/osmdroid)
The source code for these tests / examples is located under the CedarMapsSampleApp directory.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment