Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Prepare API spec #7

Open
anjesh opened this issue Jul 25, 2017 · 3 comments
Open

Prepare API spec #7

anjesh opened this issue Jul 25, 2017 · 3 comments
Assignees
@sachit-singh
Labels
documentation

Comments

@anjesh
Copy link
Collaborator

anjesh commented Jul 25, 2017 •
edited
Loading

Org-data API will be prepared to auto-suggest the organisation information in the participating-org and organisation-data form.

API Endpoints

Finding Publishers

  • GET endpoint/findpublisher?name=international&country=NP
  • GET endpoint/findpublisher?identifier=123&country=NP

Response

[
  {  
    identifier: "GB-CHC-19022",
    type: "22",
    country: "GB",
    is_publisher: false
    names: 
    [
      { name: "Health International UK", lang:"en" }
    ]
  },
  {
    identifier: "GB-CHC-1",
    type: "21",
    country: "GB",
    is_publisher: true
    names: 
    [
      { name: "Department For International Development", lang:"en" },
      { name: "International Development Department Fr", lang:"fr" }
    ]
  }
]

Finding Organisations list (from org-id.guide)

  • GET endpoint/findorglist?country=NP

The response needs to be updated, now it just gives what is available from org.id-guide

Response

[{
 data: {
   features: null,
   availability: [
     "html"
   ],
   dataAccessDetails: null,
   licenseStatus: "closed_license",
   licenseDetails: "http://index.okfn.org/place/nepal/companies/"
 },
 links: {
   wikipedia: null,
   opencorporates: null
 },
 confirmed: true,
 url: "http://www.cro.gov.np/",
 deprecated: null,
 formerPrefixes: null,
 quality: 75,
 structure: [
   "company"
 ],
 sector: null,
 code: "NP-CRO",
 meta: {
   lastUpdated: "2016-12-02",
   source: "Desk research"
 },
 description: {
   en: "All companies operating in Nepal must register with the Office of the Company Registrar Office. This database is available for search on the Office homepage. To register a company, the promoter must submit an application as prescribed by the Ministry of Industry, Commerce, and Supplies. Online filing of the required documents has been introduced and made mandatory. After the online filing, entrepreneurs are required to visit the Office of Company Registrar and submit all the original documents for further verification. [1] [1] http://www.doingbusiness.org/data/exploreeconomies/nepal#starting-a-business"
 },
 quality_explained: {
   License: Closed License: 0,
   List type: Primary: 75
 },
 access: {
   languages: [
     "en",
     "ne"
   ],
   availableOnline: false,
   guidanceOnLocatingIds: "Users can search for identifiers using the simple, searchable database on the Office website. Identifiers will be under the column heading 'Registration No' on the search results. Company numbers are sometimes reported in the format: 45995-063-064 This is made up of two parts. A CRO number and a registration year. For example: Searching for 45995 in the Registrar database returns Young Innovations. This is their CRO number. 063-064 refers to the financial year that Young Innovations was registered. When included within the identifier, this could be reported with a dash-separator, and not slash. ",
   exampleIdentifiers: "45995, 34774, 105299",
   onlineAccessDetails: "Data available for free from search on Office website homepage",
   publicDatabase: "http://www.ocr.gov.np/index.php/en/"
 },
 listType: "primary",
 subnationalCoverage: null,
 name: {
   en: "Company Registrar Office",
   local: ""
 },
 coverage: [
   "NP"
 ]
},
...
...
]
@anjesh anjesh mentioned this issue Aug 3, 2017
Closed
@sachit-singh
Copy link

Data-structure

Publisher

{
     name: "YIPL",
     identifier: "NP-CRO-1234",
     country: "NP",
     type: "10"
     is_publisher: true,
     altername_names: [] // for suggestions
 }

Non-Publisher

    {
        name: "ABC",
        identifier: "NP-SWC-1234",
        country: "NP",
        type: "20"
        is_publisher: false,
        altername_names: [] // for suggestions
    }

API Endpoints

Currently Implemented

Search for Publishers/Non-Publishers

api.net/findpublisher?name=international || api.net/findpublisher?identifier=123

Search using org-id.guide json

api.net/findorg?country=NP

API Response

Publisher/Non-Publisher Search

                       [{
                           name: "Health International UK",
                           identifier: "GB-CHC-19022",
                           type: "22",
                           country: "GB",
                           is_publisher: false
                       },{
                           name: "Department For International Development",
                           identifier: "GB-CHC-1",
                           type: "21",
                           country: "GB",
                           is_publisher: true
                       }]

Search using org-id.guide json

                       [{
                           data: {
                             features: null,
                             availability: [
                               "html"
                             ],
                             dataAccessDetails: null,
                             licenseStatus: "closed_license",
                             licenseDetails: "http://index.okfn.org/place/nepal/companies/"
                           },
                           links: {
                             wikipedia: null,
                             opencorporates: null
                           },
                           confirmed: true,
                           url: "http://www.cro.gov.np/",
                           deprecated: null,
                           formerPrefixes: null,
                           quality: 75,
                           structure: [
                             "company"
                           ],
                           sector: null,
                           code: "NP-CRO",
                           meta: {
                             lastUpdated: "2016-12-02",
                             source: "Desk research"
                           },
                           description: {
                             en: "All companies operating in Nepal must register with the Office of the Company Registrar Office. This database is available for search on the Office homepage. To register a company, the promoter must submit an application as prescribed by the Ministry of Industry, Commerce, and Supplies. Online filing of the required documents has been introduced and made mandatory. After the online filing, entrepreneurs are required to visit the Office of Company Registrar and submit all the original documents for further verification. [1] [1] http://www.doingbusiness.org/data/exploreeconomies/nepal#starting-a-business"
                           },
                           quality_explained: {
                             License: Closed License: 0,
                             List type: Primary: 75
                           },
                           access: {
                             languages: [
                               "en",
                               "ne"
                             ],
                             availableOnline: false,
                             guidanceOnLocatingIds: "Users can search for identifiers using the simple, searchable database on the Office website. Identifiers will be under the column heading 'Registration No' on the search results. Company numbers are sometimes reported in the format: 45995-063-064 This is made up of two parts. A CRO number and a registration year. For example: Searching for 45995 in the Registrar database returns Young Innovations. This is their CRO number. 063-064 refers to the financial year that Young Innovations was registered. When included within the identifier, this could be reported with a dash-separator, and not slash. ",
                             exampleIdentifiers: "45995, 34774, 105299",
                             onlineAccessDetails: "Data available for free from search on Office website homepage",
                             publicDatabase: "http://www.ocr.gov.np/index.php/en/"
                           },
                           listType: "primary",
                           subnationalCoverage: null,
                           name: {
                             en: "Company Registrar Office",
                             local: ""
                           },
                           coverage: [
                             "NP"
                           ]
                         },
                         {
                           data: {
                             features: [
                               "registered_address",
                               "organisation_name",
                               "phone_number",
                               "registration_number",
                               "activities/sector_code"
                             ],
                             availability: [
                               "html"
                             ],
                             dataAccessDetails: null,
                             licenseStatus: "closed_license",
                             licenseDetails: null
                           },
                           links: {
                             wikipedia: null,
                             opencorporates: null
                           },
                           confirmed: true,
                           url: "http://www.swc.org.np/",
                           deprecated: null,
                           formerPrefixes: null,
                           quality: 50,
                           structure: [
                             "charity"
                           ],
                           sector: null,
                           code: "NP-SWC",
                           meta: {
                             lastUpdated: "2016-12-02",
                             source: "Desk research"
                           },
                           description: {
                             en: "International NGOs wishing to operate in Nepal must register with the Social Welfare Council. Upon registration, these INGOs receive an Affiliation Certificate and an SWC Affiliation Number. This database can be searched on the website. Local NGOs do not need to be associated with the SWC, but may register with their local District Administration Office (DAO). The SWC list is thus not a complete list of all NGOs working in Nepal. "1. As laid down in article 12, Section 1, of the Social Welfare Act 2049, the international non-governmental organizations (INGOs) seeking to work in the Kingdom of Nepal must apply to the Social Welfare Council and seek permission prior to starting work." [1] [1] Document available for download at - http://www.swc.org.np/?page_id=47"
                           },
                           quality_explained: {
                             License: Closed License: 0,
                             List type: Secondary: 50
                           },
                           access: {
                             languages: [
                               "en",
                               "ne"
                             ],
                             availableOnline: false,
                             guidanceOnLocatingIds: "Users can find identifiers on the simple, searchable database on the SWC website. Identifiers will be under the column heading 'Swc Aff No'",
                             exampleIdentifiers: "37625, 14902, 28632",
                             onlineAccessDetails: "Data available in simple, searchable databse",
                             publicDatabase: "http://www.swc.org.np/?p=228"
                           },
                           listType: "secondary",
                           subnationalCoverage: null,
                           name: {
                             en: "Social Welfare Council Nepal",
                             local: ""
                           },
                           coverage: [
                             "NP"
                           ]
                         },
                         {
                           data: {
                             features: [
                               "registration_number",
                               "organisation_name",
                               "objectives/purpose",
                               "organisation_type",
                               "website"
                             ],
                             availability: [
                               "csv",
                               "html",
                               "json",
                               "xml"
                             ],
                             dataAccessDetails: null,
                             licenseStatus: "open_license",
                             licenseDetails: "http://iatistandard.org/202/license/"
                           },
                           links: {
                             wikipedia: null,
                             opencorporates: null
                           },
                           confirmed: true,
                           url: "http://iatistandard.org/codelists/IATIOrganisationIdentifier/",
                           deprecated: null,
                           formerPrefixes: null,
                           quality: 13,
                           structure: [
                             "company",
                             "government_agency",
                             "charity"
                           ],
                           sector: null,
                           code: "XI-IATI",
                           meta: {
                             lastUpdated: "2016-12-27",
                             source: "Desk research"
                           },
                           description: {
                             en: "XI-IATI is a list of organisation identifiers that is maintained by the IATI Secretariat. Any publisher may apply to the IATI Technical Team for an identifier to be generated. "If a bona fide organisation is not registered with any recognised or appropriate registration agency (http://iatistandard.org/202/codelists/OrganisationRegistrationAgency/) they should contact the IATI Technical Team who will exceptionally allocate an organisation identifier using the XI-IATI prefix. While some of these identifiers have been derived from DAC codes, this ‘meaning’ is not carried forward. i.e. IATI generated identifiers have no intrinsic meaning. For general guidance about constructing Organisation Identifiers, please see http://iatistandard.org/organisation-identifiers/" [1] [1] http://iatistandard.org/202/codelists/IATIOrganisationIdentifier/"
                           },
                           quality_explained: {
                             Availability: XML format: 1,
                             Availability: CSV format: 1,
                             Availability: JSON format: 1,
                             License: Open License: 10
                           },
                           access: {
                             languages: [
                               "en"
                             ],
                             availableOnline: false,
                             guidanceOnLocatingIds: "Users can find the codelist in three formats - CSV, JSON and XML - from the IATI Organisation Identifier website. The codelist is also available in the three different versions of the IATI Standard. Once users have downloaded the file, the identifiers will be under the column header/tag "code"",
                             exampleIdentifiers: "XI-IATI-IADB, XI-IATI-WAI, XI-IATI-1001",
                             onlineAccessDetails: null,
                             publicDatabase: "http://iatistandard.org/202/codelists/IATIOrganisationIdentifier/"
                           },
                           listType: "third-party",
                           subnationalCoverage: null,
                           name: {
                             en: "International Aid Transparency Initiative Organisation Identifier",
                             local: ""
                           },
                           coverage: null
                         },
                         {
                           data: {
                             features: [
                               "akas",
                               "organisation_name"
                             ],
                             availability: [
                               "xml",
                               "api"
                             ],
                             dataAccessDetails: "A list of identifiers is available via an XML API. ",
                             licenseStatus: "no_license",
                             licenseDetails: "No explicit license is given, though the terms and conditions encourage attribution (https://fts.unocha.org/pageloader.aspx?page=contact-ContactUs&select=3) and note that the data may contain contributions from multiple sources."
                           },
                           links: {
                             wikipedia: null,
                             opencorporates: null
                           },
                           confirmed: true,
                           url: "http://www.unocha.org",
                           deprecated: null,
                           formerPrefixes: null,
                           quality: 13,
                           structure: null,
                           sector: [
                             "humanitarian_relief"
                           ],
                           code: "XM-OCHA",
                           meta: {
                             lastUpdated: "2016-12-27",
                             source: "Desk research"
                           },
                           description: {
                             en: "OCHA (Office for the Coordination of Humanitarian Affairs) is the part of the United Nations Secretariat responsible for bringing together humanitarian actors to ensure a coherent response to emergencies. The Financial Tracking Service assigns it's own organisation identifiers to parties involved in funding or delivery of humanitarian work, which are used in UN OCHA data, and may be used by some third-parties. "
                           },
                           quality_explained: {
                             Availability: XML format: 1,
                             License: No License: 5,
                             Availability: API: 2,
                             List type: Local: 5
                           },
                           access: {
                             languages: [
                               "en"
                             ],
                             availableOnline: false,
                             guidanceOnLocatingIds: "A list of identifiers is available in XML form from the UN OCHA Financial Tracking Service API [1] at http://fts.unocha.org/api/v1/Organization.xml The identifier, following the UNOCHA pattern of usage, is made up of the id field from the XML, prefixed with 'FTS' to give identifiers of the form: > XM-OCHA-FTS8908 [1]: http://fts.unocha.org/api/Files/APIUserdocumentation.htm",
                             exampleIdentifiers: "FTS8908, FTS5191",
                             onlineAccessDetails: "A list of identifiers is available via an XML API. ",
                             publicDatabase: "https://fts.unocha.org/"
                           },
                           listType: "local",
                           subnationalCoverage: null,
                           name: {
                             en: "United Nations Office for the Coordination of Humanitarian Affairs - Financial Tracking Services Identifiers",
                             local: ""
                           },
                           coverage: null
                         },
                         {
                           data: {
                             features: [
                               "organisation_name"
                             ],
                             availability: [
                               "excel"
                             ],
                             dataAccessDetails: "Data is available in Excel file that contains much formatting.",
                             licenseStatus: "no_license",
                             licenseDetails: null
                           },
                           links: {
                             wikipedia: null,
                             opencorporates: null
                           },
                           confirmed: true,
                           url: "http://www.oecd.org/dac/stats/dacandcrscodelists.htm",
                           deprecated: null,
                           formerPrefixes: null,
                           quality: 6,
                           structure: [
                             "company",
                             "government_agency",
                             "charity"
                           ],
                           sector: null,
                           code: "XM-DAC",
                           meta: {
                             lastUpdated: "2016-12-27",
                             source: "Desk research"
                           },
                           description: {
                             en: "The Organisation for Economic Co-operation and Development (OECD) Development Assistance Committee (DAC) has created a list of organisations whom are involved in the transfer of financial flows within the work of the OECD DAC. A list of all the Donors, Agencies and Recipients can be downloaded from the OECD website. This list is updated every three years. See Donor, Agency and Delivery Channel codes. "The overarching objective of the DAC for 2011-2015 is to promote development co-operation and other policies so as to contribute to sustainable development, including pro-poor economic growth, poverty reduction, improvement of living standards in developing countries, and to a future in which no country will depend on aid." [1] "The DAC revises the list every three years. Countries that have exceeded the high-income threshold for three consecutive years at the time of the review are removed." [2] [1] http://www.oecd.org/dac/thedevelopmentassistancecommitteesmandate.htm [2] http://www.oecd.org/dac/stats/daclist.htm"
                           },
                           quality_explained: {
                             Availability: Excel format: 1,
                             License: No License: 5
                           },
                           access: {
                             languages: [
                               "en",
                               "fr"
                             ],
                             availableOnline: false,
                             guidanceOnLocatingIds: "Users can download an Excel file of the DAC and CRS codes from the OECD website. Organisation identifiers can be found in the tabs 'See Donor', 'Agency' and 'Delivery Channel' codes. Identifiers will be under 'Donor code' and 'Channel ID' respectively. Users should not that the data is available in a Excel file that contains much formatting.",
                             exampleIdentifiers: "7, 104, 914, 1312",
                             onlineAccessDetails: null,
                             publicDatabase: "http://www.oecd.org/dac/stats/dacandcrscodelists.htm / http://www.oecd.org/dac/stats/documentupload/Codelist_July_2016.xls"
                           },
                           listType: "third-party",
                           subnationalCoverage: null,
                           name: {
                             en: "OECD Development Assistance Committee",
                             local: ""
                           },
                           coverage: null
                         }]

@timgdavies
Copy link

You may want to consider implementing a country restriction on api.net/findpublisher?name=X such that searches might be api.net/findpublisher?name=international?country=NP to avoid people accidentally picking an organisation from the wrong country.

@anjesh anjesh mentioned this issue Sep 11, 2017
Open
2 tasks
@anjesh
Copy link
Collaborator Author

anjesh commented Sep 14, 2017

@sachit-singh could you please update the API spec for the org-id.guide API so that the response contains only those information that is needed for us, making the payload small. Thanks

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@sachit-singh sachit-singh

Labels
documentation
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
3 participants
@anjesh @timgdavies @sachit-singh