API Request/Call

This document will guide you on how to interact with the system, make requests, and retrieve information such as datasets, tags, and vocabulary details. The functionalities described here are largely adapted from the CKAN API Guide.

---

Base URL:

https://ugos.info/api/3/action/

All API requests are sent as HTTP GET requests, and the responses are returned in JSON format.

Response Format:

• Successful response: json { "success": true, "result": { // response data } }
• Error response: json { "success": false, "error": { "message": "Error message here", "code": 400 } }

Make sure to handle the response by checking the success flag in your application logic.

---

Endpoints and Examples

- Package List

• Description: Retrieve a list of all datasets in the catalog.
• Endpoint: https://ugos.info/api/3/action/package_list

• Method: GET

• Example Usage: bash curl https://ugos.info/api/3/action/package_list

• Example Response: json { "success": true, "result": [ "dataset_1", "dataset_2", "dataset_3" ] }

---

- Source List

• Description: Retrieve a list of all available sources.
• Endpoint: https://ugos.info/api/3/action/group_list

• Method: GET

• Example Usage: bash curl https://ugos.info/api/3/action/group_list

• Example Response: json { "success": true, "result": [ "source_1", "source_2", "source_3" ] }

---

- Organization List

• Description: Retrieve a list of all available organizations.
• Endpoint: https://ugos.info/api/3/action/organization_list

• Method: GET

• Example Usage: bash curl https://ugos.info/api/3/action/organization_list

• Example Response: json { "success": true, "result": [ "organization_1", "organization_2", "organization_3" ] }

---

- Tag List

• Description: Retrieve a list of all available tags.
• Endpoint: https://ugos.info/api/3/action/tag_list

• Method: GET

• Example Usage: bash curl https://ugos.info/api/3/action/tag_list

• Example Response: json { "success": true, "result": [ "pressure", "ocean", "wind" ] }

---

- Display Package Details

• Description: Retrieve complete details of a specific dataset.
• Endpoint: https://ugos.info/api/3/action/package_show?id={dataset_id}

• Method: GET

• Example Usage: bash curl https://ugos.info/api/3/action/package_show?id=argo-float-wmo-4903232

• Example Response: json { "help": "https://ugos.info/api/3/action/help_show?name=package_show", "success": true, "result": { "author": "Heather H Furey", "creator_user_id": "10b8a05d-e99f-4946-b06f-50d3b692a7d6", "id": "4578fe71-bdba-4e9a-9c50-60d0d3591f6a", // additional dataset details } }

---

- Display Tag Details

• Description: Retrieve details about a specific tag.
• Endpoint: https://ugos.info/api/3/action/tag_show?id={tag_name}

• Method: GET

• Example Usage: bash curl https://ugos.info/api/3/action/tag_show?id=shell

• Example Response: json { "help": "https://ugos.info/api/3/action/help_show?name=tag_show", "success": true, "result": { "id": "8f5f0a5f-371f-45d6-a812-f2d8083691f6", "name": "shell", "vocabulary_id": null, "display_name": "shell" } }

---

- Display Source Details

• Description: Retrieve details about a specific source.
• Endpoint: https://ugos.info/api/3/action/group_show?id={source_name}

• Method: GET

• Example Usage: bash curl https://ugos.info/api/3/action/group_show?id=adcp

• Example Response: json { "help": "https://ugos.info/api/3/action/help_show?name=group_show", "success": true, "result": { "approval_status": "approved", "created": "2024-06-25T22:15:10.838752", // additional details } }

---

- Display Organization Details

• Description: Retrieve details about a specific organization.
• Endpoint: https://ugos.info/api/3/action/organization_show?id={organization_name}

• Method: GET

• Example Usage: bash curl https://ugos.info/api/3/action/organization_show?id=atp-oil-and-gas-corporation

• Example Response: json { "help": "https://ugos.info/api/3/action/help_show?name=organization_show", "success": true, "result": { "approval_status": "approved", "created": "2024-08-02T20:29:54.700280", // additional details } }

---

- Search datasets by Tags

• Description: Search for datasets related to a specific tag.
• Endpoint: https://ugos.info/api/3/action/package_search?q=tags:{tag_name}

• Method: GET

• Example Usage: bash curl https://ugos.info/api/3/action/package_search?q=tags:ocean

• Example Response: json { "success": true, "result": { "count": 8, "facets": { // additional details } } }

---

- Top 10 Tags

• Description: Retrieve the top 10 tags used by datasets in the catalog.
• Endpoint: https://ugos.info/api/3/action/package_search?facet.field=["tags"]&facet.limit=10&rows=0

• Method: GET

• Example Usage: bash curl 'https://ugos.info/api/3/action/package_search?facet.field=["tags"]&facet.limit=10&rows=0'

• Example Response: json { "success": true, "result": { "count": 0, "facets": { "tags": { "ocean": 12, "wind": 8, "pressure": 5 } } } }

---

- Top 10 tags and vocabulary tags used by datasets

• Description: Retrieve top 10 tags and vocabulary tags used by datasets
• Endpoint: https://ugos.info/api/3/action/package_search?fq=vocab_{vocabulary_name}:{tag_name}

• Method: GET

• Example Usage: bash curl 'https://ugos.info/api/action/package_search?facet.field=[%22tags%22]&facet.limit=10&rows=0'

• Example Response: json { "success": true, "result": { "count": 0, "facets": { "tags": { "ocean": 12, "wind": 8, "pressure": 5 } } } }

---

- Datasets (packages) of a source

• Description: Return the datasets (packages) of a source
• Endpoint: https://ugos.info/api/3/action/group_package_show?id={source_name}

• Method: GET

• Example Usage: bash curl 'https://ugos.info/api/3/action/group_package_show?id=adcp'

• Example Response: json { "help": "https://ugos.info/api/3/action/help_show?name=group_package_show", "success": true, "result": [ { "author": null, "author_email": null, "creator_user_id": "57d270c7-b8bd-45f0-84f9-e5512d89ed79", "id": "1b951b30-e020-4018-958f-c8cab40d39aa", "isopen": true, } ] }