# mapservice-clientlib
[](https://pypi.org/project/mapservice-clientlib/)
[](https://coveralls.io/github/consbio/mapservice-clientlib?branch=main)
A library to make web service calls to map service REST APIs easier. Currently supported:
- ArcGIS (version 10.1 and greater)
- THREDDS
- WMS / NcWMS (versions 1.1.1 and 1.3.0)
- ScienceBase
Each leverages the [restle](https://github.com/consbio/restle) library to represent queried map service data as Python objects.
Each also provides some default functionality for rendering projected map service data as images, which may be overridden per class as needed.
Beyond this are some utilities for working with images (PIL) and extents (mostly Geographic, Web Mercator and other proj4 compatible projections).
## Installation
Install with `pip install mapservice-clientlib`.
## Usage
Below are some examples of each supported map service web API standard:
### ArcGIS Resources
ArcGIS Map, Feature and Image services may be queried.
```python
from clients.arcgis import MapServerResource, ArcGISSecureResource
from clients.arcgis import FeatureLayerResource, FeatureServerResource, ImageServerResource
from clients.utils.geometry import Extent
# Query the feature service, or an individual layer (lazy=False: query executed right away)
client = FeatureServerResource.get(service_url, lazy=False)
layer = FeatureLayerResource.get(service_url + "/0", lazy=False)
# Query an image service lazily (default behavior: executes query on property reference)
client = ImageServerResource.get(service_url, lazy=True)
client.extent # Query executes here
# Query a map service and generate an image
arcgis_image = MapServerResource.get(service_url).get_image(
extent, width=400, height=200,
layers="show:0",
layer_defs="<arcgis_layer_defs>",
time="<arcgis_time_val>",
custom_renderers={} # Renderer JSON
)
# Query a secure map service (generates token from URL and credentials)
client = MapServerResource.get(service_url, username="user", password="pass")
# Query a secure map service with existing token
token_obj = ArcGISSecureResource.generate_token(
service_url, "user", "pass", duration=15
)
client = MapServerResource.get(service_url, token=token_obj.token)
# Reproject an ArcGIS extent to Web Mercator
old_extent = Extent(
{'xmin': -180.0000, 'xmax': 180.0000, 'ymin': -90.0000, 'ymax': 90.0000},
spatial_reference={'wkid': 4326}
)
geometry_url = 'http://tasks.arcgisonline.com/arcgis/rest/services/Geometry/GeometryServer'
client = GeometryServiceClient(geometry_url)
extent = client.project_extent(old_extent, {'wkid': 3857}).limit_to_global_extent()
```
### WMS
WMS services may be queried, with support for NcWMS
```python
from clients.wms import WMSResource
# Query a secure WMS service
client = WMSResource.get(
url=wms_url, token="token", token_id="josso", version="1.3.0", spatial_ref="EPSG:3857"
)
# Query a public WMS service and generate an image (supports NcWMS as well)
wms_image = WMSResource.get(
wms_url
).get_image(
extent, width=400, height=200,
layer_ids=[...],
style_ids=[...],
time_range="<wms_time_val>",
params={...}, # Additional image params
image_format="png"
)
```
### THREDDS
THREDDS resources may be queried, with metadata from related WMS endpoint:
```python
from clients.thredds import ThreddsResource
client = ThreddsResource.get(url)
# See gis-metadata-parser for more
metadata = client._metadata_parser
metadata.data_credits
metadata.use_constraints
# Makes a WMS image request
thredds_image = client.get_image(
extent, width, height,
layer_ids=[...],
style_ids=[...],
time_range="<wms_time_val>",
params={...}, # Additional image params
image_format="png"
)
```
### ScienceBase
Public and private ScienceBase items may be queried:
```python
from clients.sciencebase import ScienceBaseResource, ScienceBaseSession
# Query a public ScienceBase item
client = ScienceBaseResource.get(service_url, lazy=False)
client.summary
# Query a private WMS-backed ScienceBase item
sb_session = ScienceBaseSession(
josso_session_id="token",
username="sciencebase_user"
)
sb_session.login("sciencebase_user", "pass")
client = ScienceBaseResource.get(
url=service_url,
lazy=False,
session=sb_session,
# Same token for WMS as for base item
token=sb_session._jossosessionid
)
client.service_client.full_extent # WMSResource.full_extent
# Query a private ArcGIS-backed ScienceBase item
sb_session = ScienceBaseSession(
josso_session_id="token",
username="sciencebase_user"
)
sb_session.login("sciencebase_user", "pass")
client = ScienceBaseResource.get(
url=service_url,
lazy=False,
session=sb_session,
token=sb_session._jossosessionid,
# Separate credentials for ArcGIS service
arcgis_credentials={
# Or just use "token": "existing_token"
"username": "arcgis_user",
"password": "arcgis_pass"
}
)
client.service_client.full_extent # ArcGISResource.full_extent
```
### Extent Utilities
Extent objects have a number of useful methods. Here are some examples that support projection:
```python
from clients.utils.geometry import Extent
extent_from_dict = Extent({
"xmin": -180.0, "ymin": -90.0, "xmax": 180.0, "ymax": 90.0,
"spatial_reference": {"wkid": 4326}
})
web_mercator_extent = extent_from_dict.project_to_web_mercator()
extent_from_list = Extent(
# In order of xmin, ymin, xmax, ymax
[-20037508.342789244, -20037471.205137067, 20037508.342789244, 20037471.20513706],
spatial_reference="EPSG:3857"
)
geographic_extent = extent_from_dict.project_to_geographic()
```
Raw data
{
"_id": null,
"home_page": "https://github.com/consbio/mapservice-clientlib/",
"name": "mapservice-clientlib",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8,<4.0",
"maintainer_email": "",
"keywords": "arcgis,thredds,ncwms,wms,sciencebase,geospatial,gis,mapservice,map service,clients,mapservice_clientlib",
"author": "dharvey-consbio",
"author_email": "dani.harvey@consbio.org",
"download_url": "https://files.pythonhosted.org/packages/c2/92/e211ed78cb721611de193ca8b9d7bc0408279507439e60989b6ee9bea3d0/mapservice_clientlib-2.3.0.tar.gz",
"platform": null,
"description": "# mapservice-clientlib\n\n[](https://pypi.org/project/mapservice-clientlib/)\n[](https://coveralls.io/github/consbio/mapservice-clientlib?branch=main)\n\nA library to make web service calls to map service REST APIs easier. Currently supported:\n\n- ArcGIS (version 10.1 and greater)\n- THREDDS\n- WMS / NcWMS (versions 1.1.1 and 1.3.0)\n- ScienceBase\n\nEach leverages the [restle](https://github.com/consbio/restle) library to represent queried map service data as Python objects.\nEach also provides some default functionality for rendering projected map service data as images, which may be overridden per class as needed.\n\nBeyond this are some utilities for working with images (PIL) and extents (mostly Geographic, Web Mercator and other proj4 compatible projections).\n\n## Installation\n\nInstall with `pip install mapservice-clientlib`.\n\n## Usage\n\nBelow are some examples of each supported map service web API standard:\n\n### ArcGIS Resources\n\nArcGIS Map, Feature and Image services may be queried.\n\n```python\nfrom clients.arcgis import MapServerResource, ArcGISSecureResource\nfrom clients.arcgis import FeatureLayerResource, FeatureServerResource, ImageServerResource\nfrom clients.utils.geometry import Extent\n\n\n# Query the feature service, or an individual layer (lazy=False: query executed right away)\nclient = FeatureServerResource.get(service_url, lazy=False)\nlayer = FeatureLayerResource.get(service_url + \"/0\", lazy=False)\n\n# Query an image service lazily (default behavior: executes query on property reference)\nclient = ImageServerResource.get(service_url, lazy=True)\nclient.extent # Query executes here\n\n# Query a map service and generate an image\narcgis_image = MapServerResource.get(service_url).get_image(\n extent, width=400, height=200,\n layers=\"show:0\",\n layer_defs=\"<arcgis_layer_defs>\",\n time=\"<arcgis_time_val>\",\n custom_renderers={} # Renderer JSON\n)\n\n# Query a secure map service (generates token from URL and credentials)\nclient = MapServerResource.get(service_url, username=\"user\", password=\"pass\")\n\n# Query a secure map service with existing token\ntoken_obj = ArcGISSecureResource.generate_token(\n service_url, \"user\", \"pass\", duration=15\n)\nclient = MapServerResource.get(service_url, token=token_obj.token)\n\n# Reproject an ArcGIS extent to Web Mercator\nold_extent = Extent(\n {'xmin': -180.0000, 'xmax': 180.0000, 'ymin': -90.0000, 'ymax': 90.0000},\n spatial_reference={'wkid': 4326}\n)\ngeometry_url = 'http://tasks.arcgisonline.com/arcgis/rest/services/Geometry/GeometryServer'\nclient = GeometryServiceClient(geometry_url)\nextent = client.project_extent(old_extent, {'wkid': 3857}).limit_to_global_extent()\n```\n\n### WMS\n\nWMS services may be queried, with support for NcWMS\n\n```python\nfrom clients.wms import WMSResource\n\n\n# Query a secure WMS service\nclient = WMSResource.get(\n url=wms_url, token=\"token\", token_id=\"josso\", version=\"1.3.0\", spatial_ref=\"EPSG:3857\"\n)\n\n# Query a public WMS service and generate an image (supports NcWMS as well)\nwms_image = WMSResource.get(\n wms_url\n).get_image(\n extent, width=400, height=200,\n layer_ids=[...],\n style_ids=[...],\n time_range=\"<wms_time_val>\",\n params={...}, # Additional image params\n image_format=\"png\"\n)\n```\n\n### THREDDS\n\nTHREDDS resources may be queried, with metadata from related WMS endpoint:\n\n```python\nfrom clients.thredds import ThreddsResource\n\n\nclient = ThreddsResource.get(url)\n\n# See gis-metadata-parser for more\nmetadata = client._metadata_parser\nmetadata.data_credits\nmetadata.use_constraints\n\n# Makes a WMS image request\nthredds_image = client.get_image(\n extent, width, height,\n layer_ids=[...],\n style_ids=[...],\n time_range=\"<wms_time_val>\",\n params={...}, # Additional image params\n image_format=\"png\"\n)\n```\n\n### ScienceBase\n\nPublic and private ScienceBase items may be queried:\n\n```python\nfrom clients.sciencebase import ScienceBaseResource, ScienceBaseSession\n\n\n# Query a public ScienceBase item\nclient = ScienceBaseResource.get(service_url, lazy=False)\nclient.summary\n\n# Query a private WMS-backed ScienceBase item\n\nsb_session = ScienceBaseSession(\n josso_session_id=\"token\",\n username=\"sciencebase_user\"\n)\nsb_session.login(\"sciencebase_user\", \"pass\")\n\nclient = ScienceBaseResource.get(\n url=service_url,\n lazy=False,\n session=sb_session,\n # Same token for WMS as for base item\n token=sb_session._jossosessionid\n)\nclient.service_client.full_extent # WMSResource.full_extent\n\n# Query a private ArcGIS-backed ScienceBase item\n\nsb_session = ScienceBaseSession(\n josso_session_id=\"token\",\n username=\"sciencebase_user\"\n)\nsb_session.login(\"sciencebase_user\", \"pass\")\n\nclient = ScienceBaseResource.get(\n url=service_url,\n lazy=False,\n session=sb_session,\n token=sb_session._jossosessionid,\n # Separate credentials for ArcGIS service\n arcgis_credentials={\n # Or just use \"token\": \"existing_token\"\n \"username\": \"arcgis_user\",\n \"password\": \"arcgis_pass\"\n }\n)\nclient.service_client.full_extent # ArcGISResource.full_extent\n```\n\n### Extent Utilities\n\nExtent objects have a number of useful methods. Here are some examples that support projection:\n\n```python\nfrom clients.utils.geometry import Extent\n\n\nextent_from_dict = Extent({\n \"xmin\": -180.0, \"ymin\": -90.0, \"xmax\": 180.0, \"ymax\": 90.0,\n \"spatial_reference\": {\"wkid\": 4326}\n})\nweb_mercator_extent = extent_from_dict.project_to_web_mercator()\n\nextent_from_list = Extent(\n # In order of xmin, ymin, xmax, ymax\n [-20037508.342789244, -20037471.205137067, 20037508.342789244, 20037471.20513706],\n spatial_reference=\"EPSG:3857\"\n)\ngeographic_extent = extent_from_dict.project_to_geographic()\n```\n",
"bugtrack_url": null,
"license": "BSD",
"summary": "Library to query mapservices including ArcGIS, THREDDS, WMS and ScienceBase",
"version": "2.3.0",
"project_urls": {
"Homepage": "https://github.com/consbio/mapservice-clientlib/",
"Repository": "https://github.com/consbio/mapservice-clientlib/"
},
"split_keywords": [
"arcgis",
"thredds",
"ncwms",
"wms",
"sciencebase",
"geospatial",
"gis",
"mapservice",
"map service",
"clients",
"mapservice_clientlib"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "4c01dafea82345a514535a0a0e2edfa1b26d384c8c97f6eb6b657b2dc61a3c84",
"md5": "1d539f7792b1efb1ec6668f768b2dd6a",
"sha256": "988090d32071046c936169cc3a694d156a05ecd1f661d528583cc22648d5b6cb"
},
"downloads": -1,
"filename": "mapservice_clientlib-2.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1d539f7792b1efb1ec6668f768b2dd6a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8,<4.0",
"size": 168510,
"upload_time": "2023-06-29T19:44:15",
"upload_time_iso_8601": "2023-06-29T19:44:15.931391Z",
"url": "https://files.pythonhosted.org/packages/4c/01/dafea82345a514535a0a0e2edfa1b26d384c8c97f6eb6b657b2dc61a3c84/mapservice_clientlib-2.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c292e211ed78cb721611de193ca8b9d7bc0408279507439e60989b6ee9bea3d0",
"md5": "ba01c60ccbde3fca15560f81969e4b94",
"sha256": "58b9aa6c8bf437fae3a2e2ca24194b238795b82dec48885b179b59a0ce326964"
},
"downloads": -1,
"filename": "mapservice_clientlib-2.3.0.tar.gz",
"has_sig": false,
"md5_digest": "ba01c60ccbde3fca15560f81969e4b94",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8,<4.0",
"size": 128737,
"upload_time": "2023-06-29T19:44:17",
"upload_time_iso_8601": "2023-06-29T19:44:17.635536Z",
"url": "https://files.pythonhosted.org/packages/c2/92/e211ed78cb721611de193ca8b9d7bc0408279507439e60989b6ee9bea3d0/mapservice_clientlib-2.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-06-29 19:44:17",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "consbio",
"github_project": "mapservice-clientlib",
"travis_ci": true,
"coveralls": true,
"github_actions": true,
"lcname": "mapservice-clientlib"
}
JSON
