Skip to content

Home

Jump to bottom
benjaminleighton edited this page Sep 23, 2019 · 11 revisions

Loc-I Integration API

1. Goal/scope

Complement existing Loc-I  (see v2 component architecture) with the addition of a Loc-I Integration API (preferably OpenAPIv3) for these purposes.

Primary purposes

  1. Provide a uniform interface/standardise access to Loc-I cache resources for common operations (without needing to know SPARQL)
  2. Separate front-end/client-application-specific logic from query logic of common operations (Integration API interfacing with Application-specific APIs)
  3. Maintain a separation between API and backend implementations (changes in data models, triplestore/database implementations, load balancing, etc)
  4. Enable rapid development of new applications from reuse of query logic of common operations

Secondary purposes

  1. Provide a platform to facilitate open-source development of additional APIs
  2. Cache common operations for performance
  3. Allow API deployment in separate cache configs
  4. ... (probably others)

Future design goals

  1. Federated queries, queries across multiple caches

  2. User stories

User story 1 lookup location

As a/an... Enterprise data warehouse manager

I want to...

a) Find spatial identifier(s) for a location (geospatial feature) in my database denoted by a (i) name (ii) text description (iii) lat/long, DGGS, or GPS location

b) Add location information for a new entry for an observation or data point based on some location description (text)

so that... I can ensure consistency across my data warehouse and provide opportunities to integrate with other data

User story 2 correlate with other indexed locations

As a/an... Spatial data analyst

I want to... a) For a location (geospatial feature) in dataset A find which location(s) (geospatial feature(s)) from dataset B are contained within it 

b) map observations/data from one geography (Geofabric) to reporting units in another geography (ASGS) (reapportionment)

c) For a location (geospatial feature), find related locations (geospatial feature) within the dataset by some relationship (within, contains, overlap)

so that... I can understand influences from other domains on the location (geospatial feature) I'm interested in and retrieve related locations

  1. Issues/concerns 

1. What is deemed as common operations in the Integration API bucket?

  1. Communicating that the Integration API is a complement to the SPARQL API - full power of Loc-I and the Linked Data features

  2. API design and implementation

What do we design and implement as the Integration API?

Core Integration API endpoints

Endpoints User story Priority HTTP Parameters Expected Notes
https://api.loci.cat/v1/location/contains 2 1 GET uri={lociUri}, Areas='True' includePercentage='True', FullContainment='False', page={page_num}, offset={offsetnum}, limit={numresults} List of URIs that contains lociURI
https://api.loci.cat/v1/location/overlap 2 1 GET uri={lociUri}, Areas='True', includePercentage='True', FullContainment='False', page={page_num}, offset={offsetnum}, limit={numresults} For partial and full contains/withins
https://api.loci.cat/v1/location/within 2 1 GET uri={lociUri}, Areas='True', includePercentage='True', FullContainment='False', page={page_num}, offset={offsetnum}, limit={numresults} For of URIs are within lociURI
https://api.loci.cat/v1/object or https://api.loci.cat/v1/resource 2 1 GET page={page_num}, offset={offsetnum}, limit={numresults} Description of object denoted by URI could be geoFeature, prov:Location, loci:Linkset, etc Describe Query to triple store
https://api.loci.cat/v1/[location or object?]/find-by-name 1 2 GET name={lociUri}, page={page_num}, offset={offsetnum}, limit={numresults} Query by text across multiple fields for a location Could be implemented multiple ways: 1) Sparql regex if everything harmonized to use prefLabels, requires harmonization work. 2) Implement as parql regex on multiple text labels to get coverage (hackish version of 1). 3) Index with something else, eg. elastic search
https://api.loci.cat/v1/[location or object?]/find-by-point 1 3 GET lat={lociUri}, long{long}, filter by dataset page={page_num}, offset={offsetnum}, limit={numresults} Query by lat long for a location probably a realtime overlaps query of a kind May need spatial db
https://api.loci.cat/v1/[location or object?]/find-by-polygon 1 3 GET lat={lociUri}, long{long}, filter by dataset page={page_num}, offset={offsetnum}, limit={numresults} Query by polygon for a location probably a realtime overlaps May need spatial db

Unclear if in Loc-I Integration API {#unclear-if-in-loc-i-integration-api .auto-cursor-target}

Endpoints HTTP Parameters Expected Response
https://api.loci.cat/v1/object/reapportion GET from={lociUri}, to={lociUri}, value={some value} Value with the answer of the reapportionment function
https://api.loci.cat

How do we implement the Integration API?

Since GA and CSIRO teams are familiar with Python, first cut choose a Python implementation. Something that can help automate generation of a swagger doc/api for things implemented in the Integration API.

Action items

2 incomplete Leighton, Ben (L&W, Clayton) to coordinate the team (Sommer, Ashley (L&W, Dutton Park) Cox, Simon (L&W, Clayton) Seaton, Shane (L&W, Black Mountain) ) to work on v1 development and testing of loci integration API and refactoring of appropriate bits of excelerator/iderdown.  

References

  1. **Loci journey maps **https://drive.google.com/drive/folders/1Hg19o5X92d173AkFg3vVhe5dp5Xd_Nuv

  2. **AbnLookup **https://abr.business.gov.au/Tools/AbnLookup

    1. https://abr.business.gov.au/Search/ResultsActive?SearchText=farm
    2. https://abr.business.gov.au/Search/ResultsActive?SearchText=water

  3. **Anzsic code lookup **https://www.ato.gov.au/Calculators-and-tools/Business-industry-code-tool/AnzsicCoder.aspx

    1. e.g. https://www.ato.gov.au/Calculators-and-tools/Business-industry-code-tool/AnzsicCoder.aspx?s=fish
Clone this wiki locally